mcpgate

Welcome to mcpgate's documentation!

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

Read the Docs

Quick Start

Run mcpgate directly with uvx — no installation needed:

uvx mcpgate

Examples

Nametag

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

1. Start the gateway:

uvx 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.

Installation

To install mcpgate as a persistent CLI tool:

# With uv
uv tool install mcpgate
# With pipx
pipx install mcpgate

Or add it as a dependency:

uv add mcpgate
pip install mcpgate

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.