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.