mcp-go

mcp-go is a Go implementation of the Model Context Protocol (MCP), the emerging standard for connecting LLM applications to external tools, data sources, and context providers. It gives Go developers a high-level API for both sides of that connection: server.NewMCPServer to expose tools, resources, and prompts, and client.NewClient to consume them, without hand-rolling JSON-RPC framing or transport plumbing.

The library ships stdio, SSE, and streamable HTTP transports out of the box, plus an in-process transport for testing, along with support for OAuth-protected resources, sampling, elicitation, roots, and multi-round-trip tool tasks. A functional-options API (WithDescription, WithString, WithToolCapabilities, and dozens more) keeps tool and server definitions declarative, and typed-tool helpers auto-generate JSON schemas from Go structs so request validation doesn’t have to be written by hand.

What You Get

• A server package (server.NewMCPServer) for defining MCP servers with tools, resources, and prompts using a functional-options API
• A client package (client.NewClient) for connecting to any MCP server over stdio, SSE, or streamable HTTP
• Four built-in transports — stdio, SSE, streamable HTTP, and in-process (for tests) — behind one consistent server construction API
• Typed tool support that derives JSON schemas from Go structs, removing hand-written input/output schema boilerplate
• OAuth protected-resource metadata, sampling, elicitation, roots, and session management for advanced MCP capabilities
• A 20+ example gallery covering everything from a hello-world stdio tool to OAuth clients and multi-round-trip tasks

Common Use Cases

• Exposing an internal API, database, or filesystem as MCP tools that Claude or another LLM client can call
• Building a Go-based MCP client embedded in an editor, CLI, or agent runtime to consume third-party MCP tool servers
• Adding an MCP server to an existing Go service so its capabilities become directly callable by LLM agents
• Prototyping and testing MCP tool servers locally via the in-process transport before deploying over stdio or HTTP
• Building OAuth-protected MCP servers that gate tool access behind standard resource-server authentication

Under The Hood

Architecture The codebase separates into three packages with a clean dependency direction: mcp (protocol types, JSON-RPC error codes, tool/resource/prompt schema definitions — largely generated via go generate and checked by a dedicated verify-codegen CI job), server (the request-handling core in server.go, ~3,000 lines, wiring transports, hooks, sessions, and task tracking into one MCPServer type), and client (session negotiation, OAuth, sampling, and roots for the consuming side). Requests flow from a transport (stdio.go, streamable_http.go, sse.go) into request_handler.go, which dispatches by JSON-RPC method against tools/resources/prompts registered on MCPServer, with per-session tool sets and middleware hooks layered around handler execution. Because the mcp package’s schema types are code-generated from the protocol spec, changes to the core Tool/Resource abstractions ripple through all three transport implementations and are caught by the codegen-verification CI step rather than silently drifting.

Tech Stack Pure Go 1.25 with a deliberately small dependency surface: google/jsonschema-go and santhosh-tekuri/jsonschema/v6 for schema generation and validation, google/uuid for session IDs, spf13/cast for type coercion, and yosida95/uritemplate for RFC 6570 URI templates in resource definitions. HTTP transports are built directly on net/http rather than a web framework. OpenTelemetry support lives in a separate otel/go.mod submodule so tracing dependencies never leak into the core install. The documentation site (www/) is a separate Vocs (Vite/React) project, and releases are automated via a dedicated GitHub Actions workflow.

Code Quality Test files make up roughly half of the Go source (112 of 224 files), using testify assertions, with CI running go test ./... -race for both the core module and the otel submodule, plus a golangci-lint workflow and the codegen-verification check described above. Errors are modeled as typed sentinel values (ErrParseError, ErrInvalidRequest, ErrMethodNotFound, etc.) mapped to JSON-RPC error codes rather than being swallowed or stringly-typed. Naming follows idiomatic Go conventions — exported New* constructors and With* functional options throughout — giving the codebase a consistent, predictable shape across packages.

API Design The functional-options pattern (mcp.WithDescription, mcp.WithString, mcp.Required, server.WithRecovery) keeps tool and server definitions declarative and readable, and the README’s own quickstart — server, tool, handler, ServeStdio — needs under 30 lines to produce a working MCP server. Typed-tool support derives JSON schemas from Go structs automatically, and request helpers like request.RequireString push type-checking into a single call instead of manual type assertions. A 20+ example directory (OAuth clients, sampling, elicitation, roots, typed tools, multi-round-trip tasks) gives newcomers a working reference for nearly every advanced capability the spec defines.