Zero-dependency Model Context Protocol (MCP) server framework for Go — stdio and Streamable HTTP transports, plus MCP clients for both.
Zero-dependency Model Context Protocol server framework for Go. Expose your Go code as tools, resources, and prompts that AI agents can call. Stdio and Streamable HTTP transports, plus clients for both. Single binary. No runtime.
MCP Server framework for Go
Stars
1
Tools
—
Uptime
—
go get github.com/BackendStack21/go-mcp
What can you build with this?
An MCP server turns any Go program into an AI-accessible service. The AI client (Claude Desktop, Cursor, Cody) discovers your tools, calls them, and reads your resources — all over stdin/stdout JSON-RPC.
Your first MCP server — 30 seconds
package main
import (
"context"
"fmt"
"github.com/BackendStack21/go-mcp/gomcp"
)
func main() {
srv := gomcp.NewServer("greeter", "1.0.0")
srv.AddTool(gomcp.Tool{
Name: "greet",
Description: "Greet a person by name",
InputSchema: gomcp.InputSchema{
Type: "object",
Properties: map[string]gomcp.Property{
"name": {Type: "string", Description: "The name to greet"},
},
Required: []string{"name"},
},
Handler: func(ctx context.Context, args map[string]any) (string, error) {
return fmt.Sprintf("Hello, %s!", args["name"]), nil
},
})
srv.Run() // blocks on stdin
}
func main() {
srv := gomcp.NewServer("devops-assistant", "1.0.0")
// Tools: actions the AI can take
srv.AddTool(deployTool())
srv.AddTool(restartServiceTool())
srv.AddTool(runTestsTool())
// Resources: data the AI can read
srv.AddResource(deploymentStatusResource())
srv.AddResource(errorLogsResource())
srv.AddResource(metricsResource())
// Prompts: templates for common tasks
srv.AddPrompt(incidentResponsePrompt())
srv.AddPrompt(codeReviewPrompt())
srv.Run()
}
The AI now has a full DevOps toolkit — deploy, debug, monitor, and respond to incidents. All through a single binary.
API Reference
gomcp.NewServer(name, version string) *Server
Creates a new MCP server. name and version are reported to the client during the initialize handshake.
srv.AddTool(tool Tool)
Register a callable tool. The AI sees the Name, Description, and InputSchema. When called, the Handler runs.
type Tool struct {
Name string `json:"name"`
Title string `json:"title,omitempty"`
Description string `json:"description,omitempty"`
InputSchema InputSchema `json:"inputSchema"`
OutputSchema any `json:"outputSchema,omitempty"`
Annotations *ToolAnnotations `json:"annotations,omitempty"`
Handler ToolHandler `json:"-"`
}
type ToolHandler func(ctx context.Context, args map[string]any) (string, error)
srv.AddResource(res Resource)
Register a readable resource identified by URI. The AI can list available resources and read them on demand.
type Resource struct {
URI string `json:"uri"`
Name string `json:"name"`
Description string `json:"description,omitempty"`
MimeType string `json:"mimeType,omitempty"`
Handler ResourceHandler `json:"-"`
}
type ResourceHandler func(ctx context.Context) (string, error)
srv.AddPrompt(prompt Prompt)
Register a prompt template. The AI requests a prompt by name with arguments, and gets back formatted messages.
type Prompt struct {
Name string `json:"name"`
Description string `json:"description,omitempty"`
Arguments []PromptArg `json:"arguments,omitempty"`
Handler PromptHandler `json:"-"`
}
type PromptArg struct {
Name string `json:"name"`
Description string `json:"description,omitempty"`
Required bool `json:"required,omitempty"`
}
type PromptHandler func(ctx context.Context, args map[string]any) ([]PromptMessage, error)
type PromptMessage struct {
Role string `json:"role"` // "user" or "assistant"
Content any `json:"content"` // string or content block
}
// Helper:
func NewTextContent(text string) map[string]any
srv.Run() error
Starts the server loop. Reads JSON-RPC 2.0 from os.Stdin, writes responses to os.Stdout. Blocks until stdin closes (EOF).
Serves the same JSON-RPC dispatch over the MCP Streamable HTTP transport. Each POST carries one JSON-RPC message; responses are application/json or SSE (when the client's Accept prefers it), notifications get 202, and anything but POST (with a JSON body) is 405/415. Reuses MaxRequestBytes and HandlerTimeout. Stateless — no session management, no server-initiated streams.
Bearer auth — when a token is set, every request must carry Authorization: Bearer <token>; anything else gets 401 with a WWW-Authenticate: Bearer challenge. Comparison is constant-time (crypto/subtle). Pair with any external token issuer (OAuth resource server, API gateway, or a plain static key).
Origin allowlist — when set, browser requests with an Origin not on the list get 403 (DNS-rebinding / CSRF defense, per 2025-11-25 spec guidance). Non-browser clients (no Origin header) are unaffected.
Both default to off; stdio is never affected — its trust model is the user launching the process.
Same as Run / RunWithIO, but handler invocations inherit ctx. Set Server.HandlerTimeout to bound a single handler.
Protocol Support
Default protocol version: 2026-07-28. Legacy clients that still send initialize keep working — the server echoes 2024-11-05, 2025-03-26, or 2025-11-25 when asked.
Legacy handshake — reports server name, version, capabilities
notifications/initialized
Consumed silently
ping
Liveness check (kept for older clients)
tools/list
Returns metadata for all registered tools (deterministic order, optional cursor)
tools/call
Dispatches a call to the matching tool handler
resources/list
Returns metadata for all registered resources
resources/read
Reads a resource by URI
resources/templates/list
Empty catalog (spec-compliant; templates are not registered yet)
prompts/list
Returns metadata for all registered prompts
prompts/get
Builds a prompt from arguments
2026-only result fields (resultType, ttlMs, cacheScope, _meta) are emitted only when the client declares protocol version 2026-07-28. Older clients keep seeing the pre-2026 JSON shape.
Why Go?
Single binary — compile, ship, run. No runtime, no node_modules.
Cold start < 1ms — critical for MCP servers spawned per-session by AI clients.
~5 MB RSS — a full MCP server with tools, resources, and prompts runs in under 5 MB.
Zero dependencies — encoding/json, context, io, os. That's it.
Go's concurrency — run blocking operations (DB queries, HTTP calls, subprocesses) without blocking the event loop.
Examples
Every example is a working MCP server you can compile and connect to Claude Desktop: