ViperJuice/mcp-gateway

**A gateway that lets your AI coding assistant use dozens of external tools without loading them all up front.**
PMCP sits between your assistant (Claude Code, Codex, and others) and the services it can plug into — GitHub, Jira, databases, 90+ more. Instead of loading every tool's full schema before you've asked a question, it offers a short menu first and fetches the detailed schema only when a tool is actually used.
Why it exists
Assistants reach external services through **MCP** (Model Context Protocol) — a common interface for an AI to talk to other software. When an assistant connects to a dozen MCP servers directly, it loads *all* of their tool definitions into context at once.
Context is limited and metered: every tool definition costs tokens and crowds out room for the actual work. Loading 50+ tools you may never call is slow and expensive, and adding a new service usually means restarting the assistant. Anthropic has highlighted context bloat as a key challenge with MCP tooling.
PMCP is the single connection point that keeps this compact and on-demand.
Who it's for
Developers and teams running AI coding assistants with many connected tools — especially anyone hitting "too many tools" or context-full limits.
What you get
- **Lower token cost** — the assistant sees a compact capability card, not 50+ full schemas, before doing real work.
- **Load tools only when needed** — downstream servers stay dormant until first use ("lazy by default"), and eager-start only when listed in autoStart.
- **Add tools without restarting** — provision a new server on demand from a manifest of 90+.
- **One stable connection** — your assistant sees ~26 steady meta-tools instead of a shifting set of many.
- **Guardrails built in** — output size caps and optional secret redaction.
- **Works out of the box** — core capability matching needs no API key.
Quick Start
Installation
Upgrading from 2.x
3.0.0 refuses several things 2.7.3 accepted. Most importantly, a repository's
.mcp.json, .pmcp/manifest.yaml and .mcp-gateway-policy.yaml are ignored
until you approve them with pmcp trust approve .
MIGRATING.md has an upgrade checklist, a section for each
breaking change (with a check, the fix and how to verify it), and how to roll
back. To stay on 2.x for now, pin pmcp **Capability matching is built-in** — no API key needed. gateway.request_capability
> uses a pure-Python matcher that can return direct CLI guidance for installed
> native tools, MCP server candidates, or registry search guidance.
Configure with pmcp setup
PMCP includes a wizard-style helper that can render ready-to-use MCP client config for Claude and OpenCode.
The generated config only connects your client to the PMCP gateway. Downstream MCP
servers stay lazy until first use unless you add them to autoStart in your
.mcp.json.
Use pmcp setup to print the generated config:
Named profiles cover the common modes:
Write directly into your client config with --write:
Without --write, pmcp setup prints the config so you can paste it into:
- Claude: ~/.mcp.json
- OpenCode: ~/.config/opencode/opencode.json
Use shared-service HTTP mode when running one PMCP service for multiple sessions or clients. Use single-process stdio mode for local testing.
Shared Service Mode (Manual)
If you prefer manual config, point each client to the shared HTTP endpoint:
Why this mode: PMCP uses a singleton lock (~/.pmcp/gateway.lock), so multiple local launches can conflict. One shared service avoids lock collisions and keeps tool state consistent.
Shared gateway state:
- All clients connected to one PMCP HTTP gateway share downstream server connections, pending requests, provisioned tools, and live lifecycle state.
- gateway.refresh(force=true), gateway.disconnect_server(force=true), and gateway.restart_server(force=true) can cancel or interrupt downstream work started by another client using the same gateway.
- gateway.health and live pmcp status --verbose show startup policy observations for downstream servers without exposing secret values.
- --rate-limit / PMCP_RATE_LIMIT applies per observed source IP on /mcp; localhost clients and reverse-proxied clients can share one bucket unless the proxy preserves distinct client IPs.
Quick verification:
/mcp is POST-only as of 2.0.0 — a bare curl against it returns
405 Method Not Allowed with Allow: POST, DELETE, so use /health for a
liveness check.
Security
**HTTP transport is unauthenticated by default.** For any non-localhost exposure,
choose an HTTP auth mode and terminate TLS in front of PMCP.
shared-secret mode is the backward-compatible single-tenant guard. It accepts