A security gateway for MCP (Model Context Protocol) servers. It terminates streamable-HTTP MCP on the front, inspects every JSON-RPC message in both directions, and bridges to one or more backends: local stdio subprocesses or remote MCP endpoints.
MCP client ──HTTP──▶ mcpproxyd ──▶ stdio child (npx some-mcp-server)
auth │ inspect └─▶ remote MCP (https://…/mcp)
│ policy
│ audit
Your agent calls MCP servers with real credentials, and those servers are third-party code you did not write. Put mcpproxy on that path and you get:
- Policy: allow/deny tools by glob. mcpproxy strips denied tools from
tools/list, so the model never sees them. - Approvals: hold flagged tool calls until a human approves them over the REST API.
- Rug-pull detection: fingerprint every tool (name, description, input schema). If a fingerprint changes mid-session, mcpproxy kills the session or raises an alert.
- Server-request gating: the gateway denies
sampling/createMessageandelicitation/createfrom the server by default, whether the server asks directly or embeds the ask in a2026-07-28input_requiredresult. - Budgets: max calls per session, per-tool rate limits, result-size truncation.
- Audit: structured events (
mcp.tool_call,mcp.tool_denied,mcp.tools_changed, …) to logs and per-session JSONL replay files. - Auth, all three planes: inbound (who may talk to the gateway: OIDC, GitHub, AWS STS, static token), outbound (how the gateway auths to MCP servers: static headers, passthrough, full OAuth with discovery + DCR + PKCE + refresh, RFC 8693 token exchange), and an embedded OAuth authorization server so MCP clients can OAuth against the gateway itself.
- Aggregation: several backends behind one endpoint. mcpproxy prefixes
tools
<backend>_<tool>and routes each call to its backend. - Telemetry: Prometheus metrics and OTLP traces per message.
go build -o bin/mcpproxyd ./cmd/mcpproxyd
go build -o bin/mcpsmoke ./cmd/mcpsmoke
bin/mcpproxyd -config examples/01-minimal-stdio.yaml
# in another terminal: initialize → tools/list → tools/call echo
bin/mcpsmoke -url http://127.0.0.1:8000/mcp \
-tool echo -args '{"message":"hello"}'Point any MCP client (Claude Code, Cursor, MCP Inspector) at
http://127.0.0.1:8000/mcp as a streamable-HTTP server.
One YAML file. mcpproxy expands ${ENV_VAR} references at load. Full
schema in config/config.go; examples/
covers every option:
| Example | Shows |
|---|---|
| 01-minimal-stdio | smallest useful config: one stdio backend |
| 02-remote-static-auth | remote MCP with an API-key/bearer header |
| 03-policy | allow/deny globs, budgets, rug-pull mode, catalog overrides |
| 04-approvals | human review of flagged tool calls + curl walkthrough |
| 05-aggregation | many backends, one endpoint, per-backend policy |
| 06-inbound-oidc | callers authenticate with IdP-issued JWTs |
| 07-inbound-github-awssts | GitHub-token and AWS-STS inbound modes |
| 08-outbound-oauth | OAuth to a remote MCP: discovery, DCR, PKCE, refresh |
| 09-outbound-passthrough | per-user upstream credential supplied by the client |
| 10-auth-server | embedded OAuth AS + upstream IdP federation + token swap |
| 11-token-exchange | RFC 8693: exchange the caller's token for an upstream one |
| 12-observability | Prometheus, OTLP traces, session WAL, optimizer |
| 13-kitchen-sink | everything at once, commented |
Public remote MCP servers (Linear, Notion, GitHub, Stripe, Sentry, …) with
ready-to-run configs: examples/remote/.
Architecture, auth planes, pipeline internals, operations, and embedding
guide: docs/architectural/.
Running it outside hoop, on GCP or AWS: docs/deployment/.
Start with the constraints page — the daemon
keeps sessions, approvals, and auth-server state in memory, so it is
single-replica by construction and a round-robin load balancer in front of
two instances answers 404 unknown session. That page also covers the
container image, TLS termination, state volumes, and the exposure
checklist;
| Endpoint | Purpose |
|---|---|
POST /mcp |
one JSON-RPC message (initialize starts a session; later messages carry the Mcp-Session-Id header) |
GET /mcp |
SSE stream of server-initiated messages for the session. The gateway queues 64 of them; when the stream drains slower than the server sends, or is not open, the oldest is dropped, a dropped server request gets an error reply (at most 8 in flight per backend), and the backend pump never waits |
DELETE /mcp |
end the session; another caller's DELETE ends nothing |
GET /approvals/ |
pending held tool calls (bearer: approvals.api_token) |
POST /approvals/{id}/approve | /reject |
resolve a held call |
GET /healthz |
liveness |
GET /metrics |
Prometheus (when telemetry.prometheus_path set) |
/.well-known/*, /authorize, /token, /register, /callback |
embedded auth server (when auth_server set) |
A session belongs to the caller that opened it: another caller's POST or GET
answers 404, its DELETE ends nothing, and the refusal is audited as
mcp.session_refused. With inbound.mode: anonymous every caller is
anonymous and shares sessions, so a listener that more than one caller can
reach needs inbound auth.
mcpproxy serves the session-based MCP revisions through 2025-11-25.
It recognizes 2026-07-28 (the stateless revision) and refuses it with a
conformant -32022 naming 2025-11-25, so a dual-era client retries on the
session path instead of failing. A request whose mirrored Mcp-Method /
Mcp-Name / MCP-Protocol-Version headers disagree with its body is
rejected with -32020: an intermediary routing on the header and the gateway
executing the body would otherwise act on different requests.
The refusal is deliberate. Several controls — rug-pull detection, per-session
call budgets, and override un-renaming — decide by comparing across requests
in a session. Serving them statelessly today would not weaken them, it would
silently disable them, because each no-ops when its state is empty. The list
lives in Gateway.statelessBlockers; when it empties, the stateless path can
be served.
With wal_dir set, mcpproxy writes one append-only JSONL file per session,
one line per audit event, replayable for review:
cat sessions/<sid>.jsonl | jq -r '[.time,.event,.tool // "",.reason // ""] | @tsv'mcpproxy stores outbound OAuth tokens under $MCPPROXY_STATE_DIR (default
~/.mcpproxy), encrypted with AES-256-GCM under a generated keyfile. DCR
client registrations are not persisted, so a restart re-registers. The
embedded auth server keeps its sessions in memory.
The daemon is thin wiring over the library packages. Hosts such as hoop embed the gateway and supply their own implementations of:
inspect.Hooks: guardrails, data masking, AI analysis callbacksaudit.Sink: event stream consumergateway.HeldStore: approval workflow backendgateway.IdentityResolver: inbound identity (skipauth/inboundwhen the host already authenticated the caller)gateway.Observer: telemetry
inspect.Hooks.Redact masks string values, never object keys, in
tools/call, resources/read and tasks/result results: content[].text,
content[].resource.text, contents[].text and every string of
structuredContent. A client that matches keys without case could read a
value the hook never saw, so a result is withheld when the response, the
result, a content entry or its resource repeats a key or spells result,
content, contents, structuredContent, text or resource another way.
A result that is not an object, or one of those fields of an unexpected type
(a content that is not an array, a text that is not a string), is withheld
too. A null in any of those places carries no text and passes. Duplicate
keys inside structuredContent are masked.
The hook runs once per string, in turn: a structuredContent table of 1,000
rows by 10 columns costs 10,000 calls. They share the request's
RequestTimeout with the backend call, and a result still unmasked when it
expires is withheld.
A hook error withholds the result: the client gets -32010, and the hook's
error is never recorded.
A reply the gateway sends on its own to a server request carries the
context values of the session's latest request, so a TokenSource
resolves the same caller as for that request.
An sse backend opens its event stream once, at session start, with the
credential of the caller that opened the session. A token the caller
rotates later is not used on that stream; each message POST carries the
credential of its own request.
Import it the way any Go dependency is imported:
go get github.com/hoophq/mcpproxy@v0.1.0Releases are cut by CI from merged PRs; nobody tags by hand. Every PR needs
exactly one label, which PR Release Label Check enforces before merge:
| Label | Effect on merge to main |
|---|---|
major |
vX.Y.Z → v(X+1).0.0 |
minor |
vX.Y.Z → vX.(Y+1).0 |
patch |
vX.Y.Z → vX.Y.(Z+1) |
skip-release |
no tag, no release (docs, CI, refactors) |
Auto Release then creates the vX.Y.Z tag and GitHub release — that tag
is what go get github.com/hoophq/mcpproxy@vX.Y.Z resolves. Binary Release
chains off it and attaches mcpproxy_X.Y.Z_<os>_<arch>.tar.gz (.zip on
Windows) for darwin/linux/windows on amd64 and arm64, plus checksums.txt.
Each archive holds all four commands, README.md, config.example.yaml and
examples/. Re-publish binaries for an existing tag with the Binary Release
workflow's manual trigger.
Going to v2 requires the major suffix in the module path
(github.com/hoophq/mcpproxy/v2); Auto Release refuses to tag until
go.mod matches.