mcp-gateway

Make MCP servers easier for every MCP client to use. mcp-gateway is a local MCP proxy that lets you improve a backend's tool names, descriptions, parameters, prompts, resources, and server instructions without forking that backend. Calls still reach the original backend; the gateway improves the surface your client receives.

It runs one local HTTP service with an admin UI at http://127.0.0.1:9100/admin. Claude Code and Codex are supported equally as independent clients: each backend keeps its own /<backend>/mcp endpoint.

At a glance

MCP client (Claude Code, Codex, or another MCP client)
                        │
                        ▼
          mcp-gateway — localhost:9100/<backend>/mcp
                        │
                        ▼
              remote or local MCP backend

The gateway is deliberately a proxy and editor, not a replacement MCP client or an identity provider. It can rewrite what a backend advertises and optionally validate or post-process calls; it does not silently change a backend's core behavior.

Start here

Install the public PyPI distribution with uv:

uv tool install mcp-local-gateway
mcp-gateway

The distribution is named mcp-local-gateway because the unrelated mcp-gateway name was already occupied on PyPI. The command and Python package remain mcp-gateway and mcp_gateway. Existing uv tool installs of v1.1.0 or earlier need the one-time renamed-distribution migration.

On macOS, the first interactive run offers to install the resident LaunchAgent; accepting is the entire service setup. On Linux and Windows, or with mcp-gateway --foreground, it runs in the current terminal. The application owns macOS service install, upgrade, status, and removal:

mcp-gateway --service-status
mcp-gateway --uninstall-service

Open http://127.0.0.1:9100/admin to import or edit backends. If the relevant client CLI is installed, the Admin UI can register independent endpoints in Claude Code and Codex; otherwise register /<backend>/mcp manually.

A fresh run normally creates ~/.config/mcp-gateway/config.toml. The bundled DeepWiki and Context7 examples make outbound requests while capturing their initial catalogs and when tools are called. The gateway also makes one lightweight PyPI version request at startup and daily; it never auto-applies an update, tolerates offline failure, and exposes an update_check toggle in Gateway settings. Remove the sample backends and disable that toggle before starting if the environment must be network-silent.

The installation guide covers the verified GitHub Release fallback, checkout development, configuration selection, and complete service lifecycle. See the Admin guide for client registration.

Running and updating

/health answers whether the gateway process is alive and identifies the code path it is running. /ready answers whether the gateway and every enabled backend are mounted; it returns 503 while any enabled backend is unavailable.

curl -s http://127.0.0.1:9100/health
curl -s http://127.0.0.1:9100/ready

For a normal installation, one command checks PyPI, installs the exact published version, restarts the resident service when present, and requires /health plus /ready before reporting success:

mcp-gateway update

Use the same path with an exact prior version for deterministic rollback:

mcp-gateway update --version X.Y.Z

An activation failure automatically attempts to reinstall and restart the old version. Config, logs, backups, and captured state are never part of the package swap. Contributors deploying a checkout can continue to use guarded just update from a clean main branch.

What you can change

• Tool, parameter, resource, prompt, and server-instruction text.
• Visibility, injected defaults, output budgets, and per-tool behavior hooks.
• Backend configuration and independent client registrations.
• Gateway-owned Virtual Tools that compose or route backend tools at /virtual/mcp.

The detailed configuration and security contracts live in the linked manuals; this README intentionally does not duplicate them.

Validation boundaries

just check is the repeatable local quality gate. CI runs that gate and a hermetic MCP conformance job using disposable fixtures; it does not contact your personal backends or exercise your installed daemon. Those stateful, local integration checks remain your responsibility. just verify is opt-in: it may call the public DeepWiki service, sends no bearer or OAuth credentials, and is only suitable for an equivalent unprotected test instance.

Documentation

• Installation — foreground and macOS service paths, upgrades, moves, and uninstalling.
• Releases — versioning, PyPI publishing, and verified fallback artifacts.
• Admin guide — editing, registration, and Virtual Tools.
• Configuration reference — config.toml, backends, secrets, and behavior hooks.
• Operations — readiness, logs, recovery, and local verification boundaries.
• Security — network exposure, bearer tokens, OAuth, and local trust boundaries.
• Security policy — private vulnerability reporting and supported versions.
• Admin API — scripting interface and API contracts.

Contributing

Work through pull requests, with CI as the shared baseline. Start with CONTRIBUTING.md and the repository's agent instructions; they define the development workflow, validation expectations, and where to record deferred work.

License

MIT. See LICENSE.