mcp-web-gateway 0.0.0.dev0

Connecting MCP Agents to 100s of Web Services

MCP Web Gateway

The MCP Web Gateway enables AI Agents to connect Web Services by accessing API directly.

• All HTTP endpoints are exposed as MCP resources with their original HTTP URLs.
• Generic REST tools (GET, POST, PUT, PATCH, DELETE) are provided for executing requests

This design changes the abstraction for the developers: instead of writing MCP servers, they write Web APIs using familiar REST semantics.

Installation

# Basic installation
pip install mcp-web-gateway

# With agent support for running autonomous agents
pip install mcp-web-gateway[agent]

# With development dependencies
pip install mcp-web-gateway[dev]

Quick Start

1. Direct FastAPI Integration

from fastapi import FastAPI
from mcp_web_gateway import McpWebGateway

# Your existing FastAPI app
app = FastAPI()

@app.get("/users")
async def list_users():
    return [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]

@app.post("/users")
async def create_user(name: str):
    return {"id": 3, "name": name}

# Create MCP gateway from FastAPI app
mcp = McpWebGateway.from_fastapi(
    app,
    httpx_client_kwargs={"base_url": "http://localhost:8000"}
)

1. Connecting through OpenAPI specs

from mcp_web_gateway import McpWebGateway
import httpx
import json

# Load your OpenAPI spec
with open("openapi.json") as f:
    openapi_spec = json.load(f)

# Create HTTP client
client = httpx.AsyncClient(base_url="https://api.example.com")

# Create gateway server
gateway = McpWebGateway(openapi_spec, client)

# The gateway is now ready to be used by MCP clients!

3. Using the Gateway with an MCP Client

from fastmcp import Client

# Connect to the gateway
async with Client(gateway) as client:
    # Discover available resources
    resources = await client.list_resources()
    # Example: ['https+get://api.example.com/users', 'https+post://api.example.com/users']
    
    # Execute a GET request
    users = await client.call_tool("GET", {
        "url": "https+get://api.example.com/users"
    })
    
    # Execute a POST request
    new_user = await client.call_tool("POST", {
        "url": "https+post://api.example.com/users",
        "body": {"name": "Charlie"}
    })

Running the Server and Agent

Start the MCP Server

# Using the FastAPI example
fastmcp run -t streamable-http examples/fastapi_example.py

# The server will start on http://localhost:8000
# MCP endpoint will be available at http://localhost:8000/mcp/

Start an Autonomous Agent

# Ensure OPENAI_API_KEY is set in environment or fast-agent.secrets.yaml
export OPENAI_API_KEY=your-api-key

# Run the agent with the provided instructions
fast-agent go \
  -i agent/instructions.md \
  --url=http://127.0.0.1:8000/mcp/ \
  --model=gpt-4.1-mini

The agent will:

1. Connect to your MCP Web Gateway
2. Discover available API endpoints
3. Interact with users to understand their needs
4. Execute API operations on their behalf

Web Agents

The agent/instructions.md file contains an initial set of instructions for LLM agents to:

• Discover available endpoints by checking /, /llms.txt, and API documentation
• Understand API structure through systematic exploration
• Execute operations following a clear methodology: Discover → Read → Understand → Plan → Execute → Validate
• Handle errors gracefully and learn from API responses

Advanced Usage

Custom HTTP Client Configuration

# Configure authentication, headers, etc.
client = httpx.AsyncClient(
    base_url="https://api.example.com",
    headers={"Authorization": "Bearer token"},
    timeout=30.0
)

mcp = McpWebGateway(openapi_spec, client)

Examples

Check out the examples/ directory for:

• fastapi_example.py - Complete FastAPI integration with a Todo API
• More examples coming soon!

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/chughtapan/mcp-web-gateway
cd mcp-web-gateway

# Install with development dependencies
pip install -e ".[dev]"

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=mcp_web_gateway

# Run specific test file
pytest tests/unit/test_mcp_gateway.py -xvs

Code Quality

# Format code
black src/ tests/
isort src/ tests/

# Type checking
mypy src/

Acknowledgments

Built on top of the excellent FastMCP framework.

---

Note: This project is in active development.