Frequently Asked Questions

Why not just use an MCP SDK?

SDKs give you protocol correctness. They handle JSON-RPC encoding, message routing, and spec compliance. But they don't give you application structure.

Building on an SDK means solving the same problems repeatedly: input validation, schema generation, error handling, middleware, transport wiring. mcp-go solves these once—idiomatically and safely.

If you're building a one-off experiment, an SDK is fine. If you're building production services, mcp-go provides the structure you'd end up building anyway.

Is this compatible with Claude / IDE MCP clients?

Yes. mcp-go implements the full MCP specification. Servers built with mcp-go work with any MCP-compliant client, including:

  • Claude Desktop
  • VS Code extensions
  • Custom MCP clients
  • Other AI agents implementing MCP

The framework handles protocol details so you can focus on your tools and resources.

Can I run the same server over stdio and HTTP?

Yes. Your server definition is transport-agnostic. The same tools, resources, and prompts work over any transport: 

srv := mcp.NewServer(mcp.ServerInfo{Name: "my-server", Version: "1.0.0"})

// Register tools, resources, prompts...
srv.Tool("search").Handler(searchHandler)

// Option 1: stdio for CLI tools
mcp.ServeStdio(ctx, srv)

// Option 2: HTTP for web deployments
mcp.ServeHTTP(ctx, srv, ":8080")

// Option 3: Run both simultaneously
go mcp.ServeHTTP(ctx, srv, ":8080")
mcp.ServeStdio(ctx, srv)

Does it handle authentication?

No — by design. mcp-go never handles tokens, OAuth flows, or credentials. Auth lives entirely outside the library.

On the client, inject auth via the supplied http.Client transport: 

// API key, bearer, mTLS — your transport, your rules
client, _ := mcp.NewClient(url, mcp.WithHTTPClient(&http.Client{
    Transport: myAuthTransport,
}))

On the server, terminate auth at the transport/proxy layer (e.g. an API gateway or mTLS) or in your own middleware — mcp-go ships none.

How stable is the API?

mcp-go follows semantic versioning. The current API is stable for production use.

  • v1.x — Stable API. No breaking changes within minor versions.
  • Deprecations — Announced in advance with migration paths.
  • MCP spec updates — New MCP features are added as non-breaking extensions.

The goal is "boring stability"—you should be able to upgrade without surprises.

What Go version is required?

Go 1.25 or later. This is required for certain language features and dependency compatibility.

How do I handle long-running operations?

Use context for cancellation and the progress API for status updates: 

srv.Tool("process").Handler(func(ctx context.Context, in ProcessInput) (string, error) {
    progress := mcp.ProgressFromContext(ctx)
    total := float64(100)

    for i := 0; i < 100; i++ {
        select {
        case <-ctx.Done():
            return "", ctx.Err()  // Handle cancellation
        default:
            progress.Report(float64(i), &total)
            doWork()
        }
    }
    return "complete", nil
})

Can I use this for non-AI applications?

MCP is designed for AI model integration, but there's nothing stopping you from using it as a general RPC framework. However, if you don't need MCP specifically, you might be better served by gRPC, Connect, or similar.

How do I contribute?

Contributions are welcome. See the contributing guide for details.

  • Report bugs via GitHub Issues
  • Propose features via discussions
  • Submit PRs with tests