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–18 shipped, latest release v0.5.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 -32029 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.

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.

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:

   console

   Copy

   $ 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.

2. 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.

3. 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 the container's stderr (i.e. to docker logs) and mcp-gate logs has nothing to read. -c is what tells it where the journal is; --file overrides it.
• This is really about HTTP mode. In stdio mode the MCP client spawns and owns the container, so there is usually no long-lived container to exec into. A gateway you can inspect is one started separately (docker run -d --name mcp-gate …) with transport: http.
• HTTP mode needs a non-default listen_addr. The default is 127.0.0.1:28080 — loopback INSIDE the container, unreachable from the host even with -p. Set listen_addr: 0.0.0.0:<port> in the config; the gateway then refuses to start without an auth_token, on purpose ("the HTTP endpoint would be reachable from the network without authentication").

Why

An active MCP user typically has several servers configured (filesystem, GitHub, search, custom ones), each one duplicated in every client's own config. aiMCPGate gives you: