Aimcpgate

aiMCPGate

*Русская версия — README_RU.md.*

A gateway / proxy for MCP servers (Model Context Protocol) written in Go. It presents itself to an MCP client (Claude Code, Cursor, etc.) as one MCP server, while under the hood it multiplexes calls across several upstream MCP servers, aggregates their tools, prompts and resources into one catalog, and logs every call.

Status: **MVP complete (Stages 0–6) + post-MVP Stages 7–19 shipped, latest

release v0.6.0.** Phase 1 — multiplexing stdio upstreams behind a

stdio endpoint with a call log; Phase 2 — HTTP/SSE client-facing transport,

HTTP upstreams, a CLI log viewer (mcp-gate logs); release pipeline

(goreleaser, cross-compiled for linux/darwin/windows × amd64/arm64, no

CGO). Post-MVP added upstream auto-restart, hot config reload, tool

filtering/renaming, doctor, and — in v0.3.0 — full prompts/resources/

resources/templates/completion aggregation, ping, progress forwarding

and real cancellation, logging/setLevel fan-out, per-upstream call limits

(rate limit / concurrency / result truncation / timeout), a lazy catalog and

tools/list pagination, and SSE server→client streams on both the client and

the upstream side. v0.4.0 completed the server→client direction: all three

server-initiated methods — elicitation/create, sampling/createMessage and

roots/list — are proxied in all four transport combinations (stdio or

HTTP on the client side × stdio or HTTP on the upstream side); the gateway now

declares to an upstream exactly the capabilities its own client declared

instead of a blanket {}; the HTTP transport gained server-side

Mcp-Session-Id sessions with DELETE /mcp termination. v0.5.0 adds

operator observability (Stage 18): eight event kinds — upstream start

failures and supervisor give-ups, dropped notifications and server→client

requests, an HTTP upstream with no GET SSE, catalog collisions and bad URI

templates, and a result that silently bypassed max_result_bytes — now land

in the call journal (mcp-gate logs) instead of a stderr an MCP client

usually owns; config parsing became strict (unknown/misspelled keys are

fatal). It also closes the client-facing half of the guard/truncation story:

a tools/call refused by the rate-limit or concurrency guard now returns

its own JSON-RPC error code -32009 with machine-readable

data: {"retryable":true,"reason":...} instead of an indistinguishable

-32603, and a non-text result that bypassed max_result_bytes carries a

result._meta marker (content stays byte-for-byte untouched). Finally,

auth_token referencing an unset environment variable now refuses to start

the gateway instead of silently disabling HTTP authentication. v0.6.0

makes the gateway dual-era: both MCP protocol revisions are served on the

same endpoints, chosen per request. A client on the 2026-07-28 spec gets the

modern stateless surface (server/discover, result decorations such as

resultType/ttlMs/cacheScope, HTTP Mcp-Method/Mcp-Name/

MCP-Protocol-Version header validation, removed methods rejected with

-32601); a legacy client keeps its v0.5.0 behaviour byte-for-byte. An MRTR

bridge lets a modern client answer an upstream's mid-call questions

(elicitation/create, sampling/createMessage, roots/list) by retrying

the call with inputResponses — the input window equals the upstream's

call_timeout (30 s by default). The release also lands a security batch:

opt-in env_isolation: strict for stdio upstreams, always-on scrubbing of

known secret values to *** in crash logs and journal records, cleartext-HTTP

secret warnings in serve/doctor, weak file-permission warnings in

doctor, and a cap of 16 GET SSE streams per HTTP session. The toolchain

moved to Go 1.26.7, closing 34 reachable stdlib CVEs that sat in the published

v0.5.0 binaries, and release artifacts gained per-archive SBOMs (SPDX JSON)

plus cosign keyless signatures.

Upgrading to v0.6.0 — one contract change and two conditional ones:

- The gateway-busy error code is renumbered `-32029` → `-32009`. The

rate-limit / concurrency-guard refusal keeps its machine-readable

data: {"retryable":true,"reason":...}, but anything that hard-coded the

old numeric code must be updated: -32029 fell inside the -32020..-32099

band the 2026-07-28 spec reserves for protocol errors.

- An HTTP session is now capped at 16 concurrent GET SSE streams. A 17th

attempt receives HTTP 503 before any response headers; open streams are

never evicted, and closing one frees the slot. Only observable for clients

that leak streams (e.g. reconnecting without closing the old one).

- New opt-in config flag `env_isolation: "strict"` (global). The default

is unchanged — stdio upstreams still inherit the gateway's full

environment. With strict, a child process gets only a minimal

cross-platform base (PATH, HOME, TMPDIR on Unix; SystemRoot,

PATHEXT, TEMP, TMP, … on Windows) plus its own env: block, so an

upstream that relied on inherited variables must list them explicitly.

- Additive, no action needed: known secret values are scrubbed to *** in

the crash-log stderr tail, the journal err field and event details

(always on; values shorter than 8 bytes are not scrubbed); serve and

doctor warn about secrets travelling over cleartext HTTP; doctor warns

when the config or --env-file is group- or world-readable. Legacy-era

clients see no other behaviour change — byte-stability is pinned by a

golden test.

**Upgrading to v0.5.0 — three behaviour changes, none touch the config file

format itself:**

- Config parsing is now strict. A config with an unknown or misspelled

top-level or per-upstream key, which used to be silently ignored, now

fails to load. Fix the key name (the error names it) or remove it.

- `auth_token: ${VAR}` with an unset `VAR` now refuses to start, naming

the variable. Before, it silently became an empty token — which, on an

HTTP gateway, disabled the bearer check entirely with no warning. Set the

variable (or pass --env-file), or remove auth_token to run without

authentication on purpose.

- **The call journal (log_file / calls.jsonl) gained a second record

kind**, "kind":"event", alongside the existing call records. A binary at

v0.4.0 or older reading a v0.5.0 journal renders an event line as a sparse

ERR entry rather than failing — read a journal with the same or a newer

binary than the one that wrote it.

Upgrading to v0.4.0: no config-file change, but two observable HTTP-mode

behaviour changes — a session id is now mandatory on POST /mcp after

initialize (the header is returned by the initialize response), and the

upstream registry starts lazily on the first real MCP request instead of at

process start.

Not implemented: a per-client access policy.

Releases

Cross-platform binaries are built via goreleaser (.goreleaser.yaml): linux/darwin/windows × amd64/arm64, no CGO, the version is baked in via -ldflags -X main.version=..., checksums land in SHA256SUMS. Local dry run: goreleaser release --snapshot --clean. Since v0.6.0 each archive also ships an SBOM (SPDX 2.3 JSON), and SHA256SUMS carries a cosign keyless signature (.sig + .pem); the ghcr.io image manifests are signed in the registry itself (no stored key — the identity is minted via GitHub Actions OIDC and recorded in Rekor).

Install from MCP registry

Besides the raw release binaries, the gateway ships as an OCI image on GitHub Container Registry and as an npm wrapper package — the two formats MCP registries install from.

Docker:

docker run --rm -i -v $(pwd)/config.yaml:/config.yaml ghcr.io/akomyagin/aimcpgate serve

-i is mandatory: the gateway talks MCP over stdio, so the client must keep stdin open (without it the container sees EOF and exits immediately). The image has no config of its own, so mount yours — the example above mounts it onto the default path /config.yaml; any other path works with serve -c.

To reproduce a registry sandbox check (Glama.ai etc.) without any real upstream, use the demo config baked into the image — this exact command is what a sandbox should run:

docker run --rm -i ghcr.io/akomyagin/aimcpgate serve -c /demo.config.yaml

npx (downloads the prebuilt binary for your platform on first install and verifies its SHA256 checksum):

npx aimcpgate serve -c ./config.yaml

Image policy: the OCI image contains only the mcp-gate binary — no runtimes for stdio upstreams (no node/npx, python, shells). If your config launches stdio upstream servers, extend the image yourself and install what they need; HTTP upstreams work out of the box (CA certificates are included).

Demo config: demo.config.yaml and the hidden __demo-echo subcommand exist only so registry sandboxes (Glama.ai) can introspect the gateway without any real upstream — never use them in a real deployment.

Running CLI commands inside a container

doctor, catalog, call and logs are how an operator inspects a deployment. Three facts decide how they must be invoked inside a container:

1. The binary is `/mcp-gate` and it is NOT in `$PATH`. The Dockerfile does COPY mcp-gate /mcp-gate and ENTRYPOINT ["/mcp-gate"] — nothing puts it on a search path (check the Dockerfile if this ever looks wrong). So the obvious form fails:

   $ docker exec mcp-gate mcp-gate catalog -c /config.yaml

OCI runtime exec failed: exec failed: unable to start container process: exec: "mcp-gate": executable file not found in $PATH

Use the absolute path instead — that is the only difference.

1. The image is distroless, so there is no shell at all. The base is gcr.io/distroless/static-debian12:nonroot, which ships the binary and CA certificates and nothing else. docker exec mcp-gate sh -c '…' fails the same way sh is simply not there, and there is no ls/cat to look around with. Keep pipes, globbing and redirection on the HOST side of the command.
2. `docker exec` starts a NEW process; it does not query the running `serve`. doctor, catalog and call build their own registry, open their own connections to the upstreams, report and exit. Their output is therefore upstream reachability *right now*, not the state of the live gateway: if the running process lost an upstream and dropped it from its catalog, these commands will not show that. They also keep the call journal clean — they run with journaling disabled, so a call you make this way does not appear in logs.

docker exec mcp-gate /mcp-gate version

docker exec mcp-gate /mcp-gate doctor -c /config.yaml docker exec mcp-gate /mcp-gate catalog -c /config.yaml docker exec mcp-gate /mcp-gate call demo__echo '{"text":"hi"}' -c /config.yaml docker exec mcp-gate /mcp-gate logs -c /config.yaml --tail 50

The commands assume a container started detached and named, e.g. docker run -d --name mcp-gate … — unlike the foreground docker run --rm -i … example above, which exits as soon as its stdio client disconnects and leaves nothing for docker exec to reach. The config is assumed mounted on the default path /config.yaml, as in that same example; demo__echo stands in for a tool from your own catalog. A few caveats:

• `logs` is the exception to fact 3: it reads the journal FILE the running gateway writes, so it does reflect the live process. That requires log_file in the mounted config to point at a path visible inside the container, and a volume mounted there — otherwise the journal goes to