mcpgate 0.4.0
A stateless gateway that turns any OpenAPI spec into MCP tools on the fly.
License: MIT
Requires Python: >=3.14

<div align="center" markdown="1">

  [![Discord][badge-chat]][chat]
  <br>
  <br>

  | | ![Badges][label-badges] |
  |:-|:-|
  | ![Build][label-build] | [![Nox][badge-actions]][actions] [![semantic-release][badge-semantic-release]][semantic-release] [![PyPI][badge-pypi]][pypi] [![Read the Docs][badge-docs]][docs] |
  | ![Tests][label-tests] | [![coverage][badge-coverage]][coverage] [![pre-commit][badge-pre-commit]][pre-commit] [![asv][badge-asv]][asv] |
  | ![Standards][label-standards] | [![SemVer 2.0.0][badge-semver]][semver] [![Conventional Commits][badge-conventional-commits]][conventional-commits] |
  | ![Code][label-code] | [![uv][badge-uv]][uv] [![Ruff][badge-ruff]][ruff] [![Nox][badge-nox]][nox] [![Checked with mypy][badge-mypy]][mypy] |
  | ![Repo][label-repo] | [![GitHub issues][badge-issues]][issues] [![GitHub stars][badge-stars]][stars] [![GitHub license][badge-license]][license] [![All Contributors][badge-all-contributors]][contributors] [![Contributor Covenant][badge-code-of-conduct]][code-of-conduct] |
</div>

<!-- Badges -->
[badge-chat]: https://img.shields.io/badge/dynamic/json?color=green&label=chat&query=%24.approximate_presence_count&suffix=%20online&logo=discord&style=flat-square&url=https%3A%2F%2Fdiscord.com%2Fapi%2Fv10%2Finvites%2FYe9yJtZQuN%3Fwith_counts%3Dtrue
[chat]: https://discord.gg/Ye9yJtZQuN

<!-- Labels -->
[label-badges]: https://img.shields.io/badge/%F0%9F%94%96-badges-purple?style=for-the-badge
[label-build]: https://img.shields.io/badge/%F0%9F%94%A7-build-darkblue?style=flat-square
[label-tests]: https://img.shields.io/badge/%F0%9F%A7%AA-tests-darkblue?style=flat-square
[label-standards]: https://img.shields.io/badge/%F0%9F%93%91-standards-darkblue?style=flat-square
[label-code]: https://img.shields.io/badge/%F0%9F%92%BB-code-darkblue?style=flat-square
[label-repo]: https://img.shields.io/badge/%F0%9F%93%81-repo-darkblue?style=flat-square

<!-- Build -->
[badge-actions]: https://img.shields.io/github/actions/workflow/status/MicaelJarniac/mcpgate/ci.yml?branch=main&style=flat-square
[actions]: https://github.com/MicaelJarniac/mcpgate/actions
[badge-semantic-release]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079?style=flat-square
[semantic-release]: https://github.com/semantic-release/semantic-release
[badge-pypi]: https://img.shields.io/pypi/v/mcpgate?style=flat-square
[pypi]: https://pypi.org/project/mcpgate
[badge-docs]: https://img.shields.io/readthedocs/mcpgate?style=flat-square
[docs]: https://mcpgate.readthedocs.io

<!-- Tests -->
[badge-coverage]: https://img.shields.io/codecov/c/gh/MicaelJarniac/mcpgate?logo=codecov&style=flat-square
[coverage]: https://codecov.io/gh/MicaelJarniac/mcpgate
[badge-pre-commit]: https://img.shields.io/badge/pre--commit-enabled-brightgreen?style=flat-square&logo=pre-commit&logoColor=white
[pre-commit]: https://github.com/pre-commit/pre-commit
[badge-asv]: https://img.shields.io/badge/benchmarked%20by-asv-blue?style=flat-square
[asv]: https://github.com/airspeed-velocity/asv

<!-- Standards -->
[badge-semver]: https://img.shields.io/badge/SemVer-2.0.0-blue?style=flat-square&logo=semver
[semver]: https://semver.org/spec/v2.0.0.html
[badge-conventional-commits]: https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow?style=flat-square
[conventional-commits]: https://conventionalcommits.org

<!-- Code -->
[badge-uv]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json&style=flat-square
[uv]: https://github.com/astral-sh/uv
[badge-ruff]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json&style=flat-square
[ruff]: https://github.com/astral-sh/ruff
[badge-nox]: https://img.shields.io/badge/%F0%9F%A6%8A-Nox-D85E00.svg?style=flat-square
[nox]: https://github.com/wntrblm/nox
[badge-mypy]: https://img.shields.io/badge/mypy-checked-2A6DB2?style=flat-square
[mypy]: http://mypy-lang.org

<!-- Repo -->
[badge-issues]: https://img.shields.io/github/issues/MicaelJarniac/mcpgate?style=flat-square
[issues]: https://github.com/MicaelJarniac/mcpgate/issues
[badge-stars]: https://img.shields.io/github/stars/MicaelJarniac/mcpgate?style=flat-square
[stars]: https://github.com/MicaelJarniac/mcpgate/stargazers
[badge-license]: https://img.shields.io/github/license/MicaelJarniac/mcpgate?style=flat-square
[license]: https://github.com/MicaelJarniac/mcpgate/blob/main/LICENSE
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
[badge-all-contributors]: https://img.shields.io/badge/all_contributors-0-orange.svg?style=flat-square
<!-- ALL-CONTRIBUTORS-BADGE:END -->
[contributors]: #Contributors-✨
[badge-code-of-conduct]: https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa?style=flat-square
[code-of-conduct]: CODE_OF_CONDUCT.md
<!---->

# mcpgate

Welcome to **mcpgate's** documentation!

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

[Read the Docs][docs]

## Installation

### PyPI
[*mcpgate*][pypi] is available on PyPI:

```bash
# 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:
```bash
# 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:

```bash
# With uv
uvx mcpgate
# With pipx
pipx run mcpgate
```

## Usage
For more examples, see the [full documentation][docs].

```python
from mcpgate import mcp

mcp.run(transport="http")
```

## Examples

### Nametag

Connect an MCP client to the [Nametag](https://nametag.one) API without any custom server code.

**1. Start the gateway:**

```bash
uvx --prerelease=allow mcpgate --port 8000
```

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

```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](CONTRIBUTING.md).

## Contributors ✨
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
</table>

<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->

<!-- ALL-CONTRIBUTORS-LIST:END -->

## License
[MIT](../LICENSE)

This project was created with the [MicaelJarniac/crustypy](https://github.com/MicaelJarniac/crustypy) template.