Skip to main content
Glama
README.md
# mcp-gateway

_An open-source project by [Fetch Hive](https://fetchhive.com)._

**OpenAPI to MCP, with a tunnel.** Turn an OpenAPI spec, or an MCP server
already running on your machine, into an MCP endpoint any client can call:
Cursor, Codex, Claude Code, VS Code, ChatGPT, Claude, or any MCP client.

- **Live API or localhost.** Compile a public spec, or the API on your laptop:
  a WIP branch, `localhost:3000`, a Docker compose stack.
- **Public HTTPS URL, no inbound port.** Add `--tunnel` and remote clients get
  `https://<name>.mcp.fetchhive.com/mcp` while your process stays on loopback.
- **Safe defaults.** Loopback bind, bearer token required, SSRF-hardened
  outbound dialer.

Prefer a hosted MCP Gateway with tokens, quotas, and a dashboard?
https://fetchhive.com/mcp

## Two equally important flows

### 1. Local / branch API → editor

Your server is already running on this machine. It does not need to be an MCP
server. The gateway compiles the OpenAPI document and serves the MCP endpoint.
`mcp-gateway tunnel <mcp-url>` is the other flow: the local process already
speaks MCP. A plain REST app returning 404 for `POST /mcp` is expected.

Compile from a file, or from the OpenAPI URL the API already serves. Use one
`add-spec` command, not both.

```bash
mcp-gateway init --allow-private-networks
# from a file:
mcp-gateway add-spec --name demo --file ./openapi.yaml \
  --base-url http://127.0.0.1:3000 --insecure-http
# or from the URL the API already serves:
mcp-gateway add-spec --name demo \
  --url http://127.0.0.1:3000/openapi.json \
  --insecure-http --allow-private-networks
export MCP_GATEWAY_TOKEN=…   # printed once by init
mcp-gateway test demo list_pets --args '{}'
mcp-gateway serve demo
mcp-gateway inspect demo --client cursor      # or: codex | claude-code | vscode | claude
```

`--allow-private-networks` is required for loopback and RFC1918. `--insecure-http`
is required when the API speaks HTTP (typical on localhost). Both flags are
required together to fetch an `http://` spec URL, and that host must be
loopback, RFC1918, or IPv6 ULA. A public `http://` URL is refused. `--file`
does not fetch anything; `--base-url` is the origin of **this** checkout, not
production, and still needs both flags when that origin is HTTP on a private
host.

### 2. Live API → editor or agent

Same compiler, public HTTPS OpenAPI, no private-network flag.

```bash
mcp-gateway init
mcp-gateway add-spec --name demo --url https://api.example.com/openapi.json
export MCP_GATEWAY_TOKEN=…
mcp-gateway serve demo
mcp-gateway inspect demo --client cursor
```

Or skip operating a process: [hosted MCP Gateway](https://fetchhive.com/mcp?utm_source=github&utm_medium=readme&utm_campaign=openapi_mcp).
PaaS / VPS: [deploy](docs/deploy/README.md).

### 3. Local server, remote client

The process stays on loopback. An outbound tunnel gives you
`https://<slug>.mcp.fetchhive.com/mcp` for OpenAI, Claude, Cursor, and any
other client that can send a bearer header. No account. The URL is released
30 minutes after the CLI exits.

```bash
export MCP_GATEWAY_TOKEN=…
mcp-gateway serve demo --tunnel
```

The same tunnel also sits in front of an MCP server this CLI did not
compile: a Streamable HTTP URL, or a stdio server.

```bash
mcp-gateway tunnel http://127.0.0.1:8000/mcp
mcp-gateway tunnel --stdio -- npx -y @modelcontextprotocol/server-filesystem /tmp
```

On a terminal, each finished call prints the HTTP method, status, duration,
path, and the JSON-RPC method. `tools/call` also prints the tool name. That
label is omitted when the body is streamed or larger than 64 KiB. Library
info logs stay off that screen unless you set `RUST_LOG` or `[log] level`.
Colors follow `--color` and `NO_COLOR`.

Details: [Tunnel](docs/tunnel.md).

`mcp-gateway login` is optional for an anonymous URL. It stores an `fh_cli_`
account token in `credentials.toml` next to `config.toml` (mode `0600` on
Unix). `serve --name` and `tunnel --name` read that token and keep
`https://<name>.mcp.fetchhive.com/mcp` while the process is offline.
`doctor` reads the file only to report the file mode and the email.
Anonymous tunnels do not require login. See [Account](docs/cli.md#account)
and [Persistent names](docs/tunnel.md#persistent-names).

## Deploy

[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/Fetch-Hive/openapi-mcp)
[![Deploy to Heroku](https://www.herokucdn.com/deploy/button.svg)](https://www.heroku.com/deploy?template=https://github.com/Fetch-Hive/openapi-mcp)
[![Deploy to DigitalOcean](https://www.deploytodo.com/do-btn-blue.svg)](https://cloud.digitalocean.com/apps/new?repo=https://github.com/Fetch-Hive/openapi-mcp/tree/main)

Guides: [Render](docs/deploy/render.md) · [Heroku](docs/deploy/heroku.md) ·
[DigitalOcean](docs/deploy/digitalocean.md) · [Hetzner](docs/deploy/hetzner.md).
Vercel cannot run this server ([why](docs/deploy/vercel.md)).

Set `MCP_GATEWAY_TOKEN` and `MCP_GATEWAY_SPEC_URL` (HTTPS OpenAPI; loopback HTTP is the local flow above, not this image). The image
reads `PORT` itself (distroless, no shell). After deploy, paste
`mcp-gateway inspect demo --client cursor` (replace the URL with your
`https://…/mcp`) into the editor.

## Install

```bash
# Homebrew — use the fully qualified name (Homebrew 6 trusts only this formula).
# `brew tap` then `brew install mcp-gateway` is refused until you `brew trust`.
brew install Fetch-Hive/tap/mcp-gateway

# Docker (linux/amd64 and linux/arm64)
docker run --rm -p 127.0.0.1:8787:8787 ghcr.io/fetch-hive/mcp-gateway:0.11.4 version

# npm — wrapper plus the prebuilt binary for this machine
npx --yes @fetch-hive/mcp-gateway version

# GitHub Release installer
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Fetch-Hive/openapi-mcp/releases/latest/download/mcp-gateway-cli-installer.sh | sh

# From a checkout of this repo
cargo install --path crates/mcp-gateway-cli
```

`mcp-gateway` compiles OpenAPI 3.0/3.1 to a versioned IR, serves tools over
Streamable HTTP or stdio, and injects upstream credentials from env or file
references. Outbound HTTP uses an SSRF-hardened dialer.

## Security

Default bind is loopback. Binding `0.0.0.0` requires `--expose`. Upstream
private networks and localhost require `--allow-private-networks`. Report
vulnerabilities to tom@fetchhive.com — see `SECURITY.md`.

## Docs

- [Connect Cursor, Codex, Claude Code](docs/clients.md)
- [Tunnel (local server, public URL)](docs/tunnel.md)
- [CLI reference](docs/cli.md)
- [Config schema](docs/config.md)
- [Deploy (PaaS + VPS)](docs/deploy/README.md)
- [SSRF policy](docs/ssrf.md)
- [Private-network flag](docs/private-networks.md)
- [Tunnel protocol](docs/tunnel-protocol.md)

## Licence

Apache License 2.0. See `LICENSE` and `NOTICE`.