[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 (MCP), maintained in collaboration with Google. It provides both server (mcp.Server) and client (mcp.Client) implementations, stdio/HTTP transports, typed tool registration with automatic JSON-schema generation, middleware hooks, and JSON-RPC error plumbing.

gh-aw is already pinned to v1.7.0, the latest release (published 2026-07-28) — great news, no version bump needed this cycle!

Current Usage in gh-aw

• Files: 12 non-test .go files (11 in pkg/cli, 1 in pkg/parser)
• Key APIs Used:
  • Server: mcp.NewServer, mcp.AddTool (10 tools), mcp.ToolAnnotations, server.AddReceivingMiddleware
  • Transports: mcp.StdioTransport (default), mcp.NewStreamableHTTPHandler (optional --port mode)
  • Client (inspector): mcp.NewClient, mcp.CommandTransport, mcp.StreamableClientTransport, session.ListTools/ListResources
  • Progress: req.Session.NotifyProgress + req.Params.GetProgressToken() for long-running tools (logs/audit/audit-diff)
  • Tests: mcp.NewInMemoryTransports() for fast in-process client/server round-trips

Research Findings

Recent Updates

v1.7.0 is a major protocol rewrite bringing full support for MCP protocol revision 2026-07-28:

• Stateless/sessionless mode (SEP-2575) — initialize handshake replaced by per-request _meta + a new server/discover RPC. Requires StreamableHTTPOptions.Stateless = true to opt in over HTTP.
• Multi-Round-Trip Requests (SEP-2322) replacing server-to-client roots/sampling/elicitation calls.
• subscriptions/listen replacing the old list_changed/resources/updated notifications.
• HTTP header standardization (x-mcp-header passthrough) and cacheable list results (ttlMs/cacheScope).
• Formal deprecation of roots, sampling, and logging (types kept for backward compat).
• 7 MCPGODEBUG escape-hatch flags for behavior restoration, all slated for removal in v1.9.0.
• Backward compatibility with 2025-11-25 is fully preserved and auto-negotiated — nothing breaks by upgrading.

Best Practices

• Tool annotations should mix bare bool (Idempotent/ReadOnly — always serialized as of v1.7.0) and *bool (Destructive/OpenWorld — nil means "unset"). gh-aw's tool registrations already do this correctly.
• Stateless: true is recommended for HTTP servers that don't need session affinity, to access the new protocol revision and simplify session bookkeeping.

Improvement Opportunities

🏃 Quick Wins

• parser.MCPServerInfo and the gh aw mcp-inspect tool currently surface only Tools and Resources — there's no session.ListPrompts call anywhere in the codebase. Several published MCP servers expose prompts; adding a Prompts field and a ListPrompts call would give mcp-inspect full capability coverage with a small, self-contained change.

✨ Feature Opportunities

• Consider setting StreamableHTTPOptions.Stateless: true in runHTTPServer (pkg/cli/mcp_server_http.go). The --port HTTP server is loopback-only and single-user, so the 2-hour idle-session bookkeeping (SessionTimeout) isn't buying much; going stateless would simplify the code path and let the server negotiate the new 2026-07-28 protocol revision directly instead of always falling back to 2025-11-25 over HTTP.
• The new server/discover RPC and cacheable list results (ttlMs/cacheScope) aren't relevant yet since gh-aw's tool list is small and static, but worth keeping in mind if the tool surface grows significantly.

📐 Best Practice Alignment

• Progress notifications (notifyProgress in mcp_tools_privileged.go) and the custom argument-validation middleware (argumentValidationMiddleware) are both idiomatic, well-guarded (nil-checks, best-effort failure handling) uses of the SDK — no changes recommended.
• jsonrpc.Error wrapping via newMCPError correctly separates protocol-level errors from tool-level CallToolResult{IsError: true} results.

🔧 General Improvements

• None found beyond the prompts-listing gap above — the SDK usage across server, client, transports, middleware, and tests is thorough and current.

Recommendations

1. (Quick win) Add prompts listing to the mcp-inspect tool and parser.MCPServerInfo.
2. (Consider) Evaluate Stateless: true for the HTTP transport mode — low risk given it's loopback-only, and unlocks the newest protocol revision.
3. No urgent action needed otherwise — the module is already at the latest version and used idiomatically.

Next Steps

• File a follow-up issue/PR for the ListPrompts addition if desired.
• Revisit Stateless mode once there's a concrete need (e.g. a web-based MCP client wanting the newest protocol revision).

---

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

Generated by 🐹 Go Fan · agent · 139.6 AIC · ⌖ 31.4 AIC · ⊞ 7.5K · ◷

• expires on Aug 4, 2026, 1:12 AM UTC-08:00