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

[github-actions]

🐹 Go Fan Report: modelcontextprotocol/go-sdk

Module Overview

github.com/modelcontextprotocol/go-sdk is the official Go SDK for the Model Context Protocol. It provides both server and client implementations of the MCP wire protocol: typed tool registration with auto-generated JSON schemas, multiple transports (stdio / CommandTransport, streamable HTTP), sessions, middleware, progress notifications, and structured JSON-RPC errors.

This is a first-class dependency for gh-aw — the project both exposes an MCP server (gh aw mcp-server) and acts as an MCP client (the inspector). It was picked today because it is the most recently updated direct dependency in the tree (repo pushed_at = 2026-07-06) and had not been reviewed in the last 7 days.

Current Usage in gh-aw

• Files: 11 non-test .go files (26 files including tests)
• Imports: github.com/modelcontextprotocol/go-sdk/mcp (24 files) + .../jsonrpc (7 files)
• Key APIs used: mcp.NewServer/NewClient, mcp.AddTool (generic typed handlers), CallToolResult+TextContent, ToolAnnotations (OpenWorldHint/IdempotentHint/DestructiveHint), Icon, AddReceivingMiddleware, CommandTransport, StreamableClientTransport{DisableStandaloneSSE:true}, NewStreamableHTTPHandler+StreamableHTTPOptions, Session.NotifyProgress, jsonrpc.Error.

Usage highlights (all idiomatic)

• Typed tools via generics — each *Args struct carries jsonschema doc tags; schema is auto-generated (schema caching is automatic since v1.3.0, already noted in a code comment at mcp_server.go:52).
• Reflection-driven param registry — mcpToolParams() derives valid parameter names from the *Args json tags, so adding a field auto-updates the "Did you mean?" validation middleware. Nicely DRY.
• Context cancellation — management tools check ctx.Done() before running.
• Structured errors — consistent jsonrpc.Error with proper codes.
• Guarded progress — notifyProgress checks req.Session == nil and only emits when a progress token is present.
• Inspector correctly sets DisableStandaloneSSE: true (it only queries capabilities).

Research Findings

• Latest stable: v1.6.1 (2026-05-22) — matches go.mod. Latest prerelease: v1.7.0-pre.1 (2026-06-24), implementing MCP protocol revision 2026-07-28.
• Extremely active project; the SDK repo was pushed to today.

Recent Updates

• v1.6.0 — cross-origin protection default REMOVED: a nil CrossOriginProtection no longer enables origin verification (restore via MCPGODEBUG=enableoriginverification=1 or set it explicitly).
• v1.6.0 — SetError now preserves existing Content (previously overwrote). gh-aw builds results manually, so unaffected.
• v1.6.1 — MCPGODEBUG=disablecontenttypecheck=1 escape hatch for the POST Content-Type check.
• v1.7.0-pre.1 — protocol 2026-07-28 rewrite (prerelease): stateless/sessionless model (StreamableHTTPOptions.Stateless=true), server/discover replacing initialize, multi-round-trip requests, unified subscriptions/listen, cacheable list results (ttlMs/cacheScope), HTTP header standardization. Backward-compatible; negotiates down to 2025-11-25.

Best Practices

Typed-generic tool handlers with jsonschema tags, ToolAnnotations hints, structured jsonrpc errors, and explicit transport options — all of which gh-aw already follows.

Improvement Opportunities

🏃 Quick Wins

• Set CrossOriginProtection on the HTTP handler. runHTTPServer (pkg/cli/mcp_server_http.go:65) binds to :port (all interfaces) and leaves StreamableHTTPOptions.CrossOriginProtection nil. Since v1.6.0 removed the default protection, an HTTP MCP server reachable off-localhost is exposed to DNS-rebinding / cross-origin POSTs. Safer defaults: bind 127.0.0.1 (not :) and/or enable origin verification.
• Middleware error path: in argumentValidationMiddleware (pkg/cli/mcp_argument_validation.go:80), an unknown tool name escalates a tool-arg failure into a protocol-level jsonrpc.Error (CodeMethodNotFound). Returning the original tool result keeps the semantics cleaner. Low risk (registry is exhaustive) but worth a comment.

✨ Feature Opportunities

• Track v1.7.0 stable — do NOT adopt the prerelease. gh-aw's transports are local stdio + a localhost HTTP handler, so the 2026-07-28 stateless rewrite offers little immediate benefit and some churn risk. Revisit when non-pre v1.7.0 ships.
• Cacheable list results (SEP-2549): if the inspector ever polls tools/list repeatedly, ttlMs/cacheScope hints (v1.7.0) could cut redundant round-trips.

📐 Best Practice Alignment

• Usage is already idiomatic — generic typed tools, auto schema, annotation hints, guarded progress, structured errors, DisableStandaloneSSE on the inspector. No deprecated APIs in use.

🔧 General Improvements

• The new(true)/new(false) *bool idiom (Go 1.26 new-with-initializer, 5 uses) is clean and correct — no change needed.

Recommendations

1. (Security) Explicitly configure CrossOriginProtection and/or bind the HTTP MCP server to 127.0.0.1 — highest-value item given the v1.6.0 default change.
2. Add a short comment on the unknown-tool escalation in the validation middleware.
3. Stay on v1.6.1; watch for v1.7.0 stable before upgrading.

Next Steps

• Confirm the intended exposure of gh aw mcp-server --port (localhost-only vs. network) and pick the matching cross-origin posture.
• Add a watch note to re-evaluate at v1.7.0 stable.

---

Generated by Go Fan
Module summary saved to: scratchpad/mods/modelcontextprotocol-go-sdk.md

Generated by 🐹 Go Fan · 148.5 AIC · ⌖ 9.38 AIC · ⊞ 7.4K · ◷

• expires on Jul 7, 2026, 1:20 AM UTC-08:00

[github-actions]

🍪 Issue Monster selected this for Copilot

I identified this issue as a good candidate for automated resolution and requested assignment to the Copilot coding agent.

This issue is a standalone Go dependency review item focused on MCP SDK usage and appears suitable for an isolated implementation pass.

If assignment succeeds, the Copilot coding agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster · 1.75 AIC · ⌖ 4.53 AIC · ⊞ 6K · ◷