mcpgate 0.4.0

A stateless gateway that turns any OpenAPI spec into MCP tools on the fly.

mcpgate

Welcome to mcpgate's documentation!

A stateless gateway that turns any OpenAPI spec into MCP tools on the fly.

Read the Docs

Installation

PyPI

mcpgate is available on PyPI:

# With uv
uv add mcpgate
# With pip
pip install mcpgate
# With Poetry
poetry add mcpgate

GitHub

You can also install the latest version of the code directly from GitHub:

# With uv
uv add git+https://github.com/MicaelJarniac/mcpgate
# With pip
pip install git+git://github.com/MicaelJarniac/mcpgate
# With Poetry
poetry add git+git://github.com/MicaelJarniac/mcpgate

Quick Start

Run the server directly without installing:

# With uv
uvx mcpgate
# With pipx
pipx run mcpgate

Usage

For more examples, see the full documentation.

from mcpgate import mcp

mcp.run(transport="http")

Examples

Nametag

Connect an MCP client to the Nametag API without any custom server code.

1. Start the gateway:

uvx --prerelease=allow mcpgate --port 8000

2. Configure your MCP client (e.g. Claude Desktop — claude_desktop_config.json):

{
  "mcpServers": {
    "Nametag": {
      "baseUrl": "http://localhost:8000/mcp/",
      "headers": {
        "X-OpenAPI-URL": "https://app.nametag.one/api/openapi.json",
        "X-API-URL": "https://app.nametag.one",
        "X-Cookies": "YOUR_SESSION_COOKIE"
      }
    }
  }
}

To get YOUR_SESSION_COOKIE, open the Nametag web app in your browser, open DevTools → Application → Cookies, and copy the value of the session cookie (e.g. __Secure-authjs.session-token=<value>). Pass it as X-Cookies: __Secure-authjs.session-token=<value>.

The gateway fetches the OpenAPI spec from X-OpenAPI-URL once and caches it, then proxies every MCP tool call to X-API-URL with your session cookie attached — no backend changes required.

Headers

mcpgate is configured per-request via HTTP headers sent by the MCP client:

Header	Required	Description
x-openapi-url	Yes	URL of the OpenAPI JSON specification to load
x-api-url	Yes	Base URL of the target API for proxied requests
x-cookies	No	Cookie string to forward with API requests

When both x-openapi-url and x-api-url are present, mcpgate fetches the OpenAPI spec, generates MCP tools from it, and proxies tool calls to the target API. When these headers are absent, the server returns no tools.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

More details can be found in CONTRIBUTING.

Contributors ✨

License

MIT

This project was created with the MicaelJarniac/crustypy template.