[go-fan] Go Module Review: modelcontextprotocol/go-sdk

[github-actions[bot]]

🐹 Go Fan Report: MCP Go SDK

The most recently updated unreviewed direct dependency — and gh-aw's most heavily-used external module (21 files!). The v1.4.1 patch dropped just 10 days ago with a security fix that the project gets for free.

---

Module Overview

github.com/modelcontextprotocol/go-sdk is the official Go SDK for the Model Context Protocol (MCP). It provides both server and client primitives: typed tool registration, stdio/HTTP transports, resource/root querying, and OAuth. This is the backbone of the mcp-server command and the mcp inspect toolchain.

• Version in use: v1.4.1 ✅ (latest)
• MCP Spec supported: 2025-11-25 (full support)
• Repository: modelcontextprotocol/go-sdk

---

Current Usage in gh-aw

21 files use this module across the server and client layers.

Server Side (pkg/cli/mcp_server*.go, mcp_tools_*.go)

• mcp.NewServer() → configured with ServerCapabilities, custom logger, ListChanged: false
• mcp.AddTool() with typed generics: func(ctx, req, args) (*CallToolResult, any, error)
• mcp.ToolAnnotations on every tool (ReadOnlyHint, IdempotentHint, DestructiveHint, OpenWorldHint)
• mcp.Icon for emoji-based tool icons
• mcp.NewStreamableHTTPHandler() for the --port HTTP mode
• mcp.StdioTransport{} for the default stdin/stdout mode

Client Side (pkg/cli/mcp_inspect_mcp.go)

• mcp.NewClient() + mcp.CommandTransport{} for stdio MCP inspection
• mcp.StreamableClientTransport{} with DisableStandaloneSSE: true for HTTP inspection (good practice!)
• session.ListTools(), session.ListResources() to surface server capabilities

Error Handling

• jsonrpc.Error{Code, Message, Data} with a clean newMCPError() helper
• Proper use of jsonrpc.CodeInternalError, CodeInvalidParams, CodeInvalidRequest

Overall assessment: Idiomatic, well-annotated, strong error handling. The team clearly knows the SDK well.

---

Research Findings

Recent Updates (v1.4.1 — 2026-03-13)

This was a security patch release:

1. Cross-origin request protection (Go 1.25 http.CrossOriginProtection):
   • Now verifies Content-Type: application/json on POST requests
   • Blocks cross-origin requests by default
   • Customizable via StreamableHTTPOptions.CrossOriginProtection
   • Can be disabled with MCPGODEBUG=disableoriginverification=1
2. Unicode zero character handling fix in JSON parser
3. Required Go version bump to 1.25 (aligns with what go.mod already declares)

Post-Release Main Branch (not yet released)

• Fix SetProgressToken when Meta is nil (silent data loss bug, feat: only upload docs build artifacts on main branch deployment #846)
• Auth: scope returned in WWW-Authenticate header (Remove Claude engine output.txt handling as CLI no longer produces this file #834)
• Go 1.24 code cleanup (Fix: Ensure localhost domains are always included in Playwright allowed_domains #850)

Best Practices from Maintainers

• DisableStandaloneSSE: true for query-only clients → already used ✅
• ListChanged: false for static tool sets → already set ✅
• Schema caching is automatic since v1.3.0 → comment in codebase confirms awareness ✅

---

Improvement Opportunities

🏃 Quick Wins

Paginate ListTools and ListResources in the inspector

mcp_inspect_mcp.go does:

toolsResult, err := session.ListTools(listToolsCtx, &mcp.ListToolsParams{})

This fetches only the first page. If an inspected MCP server has >N tools, the remaining ones are silently dropped. The fix is straightforward — loop on toolsResult.NextCursor:

var allTools []*mcp.Tool
cursor := ""
for {
    params := &mcp.ListToolsParams{}
    if cursor != "" {
        params.Cursor = cursor
    }
    result, err := session.ListTools(ctx, params)
    if err != nil { break }
    allTools = append(allTools, result.Tools...)
    if result.NextCursor == "" { break }
    cursor = result.NextCursor
}

Same pattern for ListResources.

✨ Feature Opportunities

Progress notifications for long-running tools

logs and audit tools can take up to 50 seconds. The MCP SDK supports progress tokens:

• Client sends progressToken in CallToolParams.Meta
• Server calls session.SendProgress() to report intermediate status
• Clients that support it (Claude Desktop, etc.) show live progress

This would significantly improve UX for the two most expensive tools.

OutputSchema for structured tools

Tools like status, compile, logs, and audit return well-defined JSON objects. The SDK's mcp.Tool.OutputSchema field lets you declare the output structure, enabling clients to understand responses without parsing. The typed AddTool handler already accepts a structured second return value — using a concrete type instead of nil would unlock this.

📐 Best Practice Alignment

Document cross-origin protection behavior for HTTP users

Since v1.4.1, mcp.NewStreamableHTTPHandler silently rejects requests missing Content-Type: application/json (for POSTs) or with unexpected origins. Any HTTP MCP client that doesn't set these headers will get 403s. Worth documenting in mcp-server --port docs, along with the MCPGODEBUG=disableoriginverification=1 escape hatch for debugging.

The project is already on v1.4.1 so this protection is active now.

---

Recommendations

Priority	Action
🔴 High	Paginate ListTools/ListResources in inspector — silent data loss for large servers
🟡 Medium	Document HTTP cross-origin protection behavior + MCPGODEBUG option
🟢 Low	Add progress notifications to logs and audit tools
🟢 Low	Declare OutputSchema on structured-output tools

---

Next Steps

• Open issue for ListTools pagination fix (simple, impactful)
• Update HTTP server docs to mention v1.4.1 cross-origin behavior
• Track main-branch fix for SetProgressToken — relevant if progress support is added

---

Module summary saved to: scratchpad/mods/modelcontextprotocol-go-sdk.md

References: §23426091791

AI generated by Go Fan · history

• expires on Mar 24, 2026, 7:32 AM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Go Fan.

A newer discussion is available at Discussion #22626.