Showcase · MCP server · Go

mcp

Progressive MCP discovery and execution for Go applications: an agent reads a catalogue before it sees the tools, with the same operation tree served from a Cobra CLI or mounted in an HTTP or gRPC service.

v0.2.0, released Pre-1.0

DocsRepository

The problem it exists for

The obvious way to put a command-line tool behind MCP is one tool per command, and every one of those tools brings its schema into the agent’s context before the conversation even starts. The feasibility spike measured how that grows: about 16.7 KB for ten commands, 167 KB for a hundred and 1.67 MB for a thousand, against a fixed few hundred bytes for a small three-tool front door (the spike). On a real build, go-tool-base’s whole listing through that front door is about 1.5 KB.

How it works

Three tools in front of everything

go/mcp puts one registry behind three discovery tools: search, details and call. An operation’s schema only reaches the conversation when an agent actually asks for it. A direct mode, publishing one tool per operation, is there when a client really wants it.

Commands, HTTP and gRPC behind one registry

Command-line commands run as supervised subprocesses of the same binary, an HTTP service mounts a single handler, and gRPC methods bind in-process through the service’s own interceptors. Being listed in the catalogue isn’t permission: the policy is asked again at every step, and a denied operation answers exactly like an unknown one.

Decisions and what they cost

  • Compact by default. The three-tool front door is the default and direct publishing has to be chosen (spec 0001), rather than guessing the mode from how a client behaves. What it cost: a client’s approval prompt only ever sees the call tool, which has to carry the most cautious labels.
  • Commands run out of process. A command is run as a fresh subprocess of the tool, never in-process, because a command tree is shared mutable state. What it cost: one call at a time (a second gets an immediate, retryable busy), a five-minute limit, a megabyte of output, and stricter checking of custom flags.
  • Permission at every step. The catalogue and execution are shared by every publishing mode, and the policy is checked on each request, not just once at listing.
  • gRPC in-process. gRPC calls go through the service’s own interceptors in-process, rather than dialling the service’s own listener, which would need a service-to-itself token (spec 0002). What it cost: single request and response only; streaming methods are refused when they’re registered.

Proof in use

  • go-tool-base serves its MCP endpoint through it, so every tool generated on go-tool-base with MCP switched on gets the front door for free.
  • It’s tested against three versions of the official Go MCP SDK.

Use it when, and when not to

Use it if you want AI agents to be able to drive your Go tool’s commands or services, and your tool has enough of them that publishing every schema up front would crowd the conversation.

It doesn’t authenticate callers, and it doesn’t sandbox commands beyond a process group, so one mode of it isn’t suitable over HTTP at all. The publishing mode is fixed when the server is built, and cleanup on macOS and Windows is designed and compiled but not yet proven in CI.

Where it’s going

keryx’s studio as a second user, native macOS and Windows acceptance, gRPC streaming, and a bridge into chat.

The story in posts

Last reviewed .