[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 MCP — the foundational protocol the entire gateway is built around. It provides client/server primitives, typed request/response types, session management, transport implementations (stdio, streamable HTTP, SSE), and testing helpers.

This is the most strategically critical direct dependency: every MCP interaction flows through it.

Current Usage in gh-aw

• Files: ~40 files (production + test)
• Import alias: sdk "github.com/modelcontextprotocol/go-sdk/mcp"

API	Usage
sdk.NewClient / sdk.ClientSession	Backend MCP connections (stdio + HTTP)
sdk.CommandTransport	stdio backend launch
sdk.StreamableClientTransport	Streamable HTTP (2025-03-26 spec)
sdk.SSEClientTransport	SSE transport (2024-11-05 spec, deprecated path)
sdk.NewInMemoryTransports	In-process testing
sdk.NewServer + sdk.NewStreamableHTTPHandler	Gateway frontend MCP server
sdk.ErrSessionMissing	Typed sentinel for session-not-found (v1.5.0+)
sdk.ClientOptions.KeepAlive	Periodic pings to keep HTTP backend sessions alive
All content types	TextContent, ImageContent, AudioContent, EmbeddedResource

Key Patterns

1. Triple transport fallback: streamable HTTP → SSE → plain JSON-RPC (custom)
2. Schema bypass: server.AddTool() (method) bypasses sdk.AddTool() validation for non-standard backend schemas
3. streamableMaxRetries = -1 sentinel: disables SDK-level SSE reconnect retries; guarded by TestMaxRetriesSentinelCanary
4. Session reconnection: at-most-once reconnect with mutex serialization for both SDK and plain JSON-RPC paths

Improvement Opportunities

🏃 Quick Wins

1. Context propagation gap in SDK session calls — HIGH

The tool timeout (context.WithTimeout) applied in callBackendTool is never propagated to SDK session method calls. callSDKMethod uses c.ctx (the long-lived connection context) for all session methods:

// connection_methods.go — ignores the per-request context
return c.getSDKSession().CallTool(c.ctx, &sdk.CallToolParams{...})

But SendRequestWithServerID accepts a ctx that is only forwarded for plain JSON-RPC transport:

if c.httpTransportType == HTTPTransportPlainJSON {
    result, err = c.sendHTTPRequest(ctx, method, params)   // ctx used ✓
} else {
    result, err = c.callSDKMethodWithReconnect(method, params)  // ctx dropped ✗
}

Fix: Thread the request context through callSDKMethodWithReconnect → callSDKMethod → all SDK session calls (CallTool, ListTools, ListResources, etc.). This ensures toolTimeout actually cancels backend SDK calls.

2. Prompt passthrough gap — MEDIUM

callSDKMethod handles prompts/list and prompts/get to fetch prompts from backends, but the gateway's sdk.Server never registers prompts with server.AddPrompt(). Frontend clients cannot discover backend prompts via standard MCP prompts/list. Tools and resources are exposed; prompts are not.

✨ Feature Opportunities

3. v1.7.0 pre-release monitoring

v1.7.0-pre.1 is available while the project uses v1.6.1. The existing version-pinned comments (// Verified for go-sdk v1.6.1) need re-auditing on each SDK bump. Plan upgrade when v1.7.0 is stable.

4. Client capability declaration

All three client.Connect(ctx, transport, nil) calls pass nil for capabilities. Declaring capabilities can enable enhanced backend behaviors per the MCP spec.

📐 Best Practice Alignment

5. Missing canary for server.AddTool bypass

There's a TestMaxRetriesSentinelCanary protecting the streamableMaxRetries sentinel. But there's no equivalent test verifying that server.AddTool (method) skips argument validation while sdk.AddTool (function) enforces it — behavior the gateway depends on. A canary test would guard against silent breakage on SDK upgrades.

6. Schema normalization completeness

NormalizeInputSchema handles nil schemas, missing type, and missing properties, but the gateway still bypasses sdk.AddTool entirely. If normalization were extended to handle all edge cases (e.g., $schema annotations from draft-07 backends), the bypass could be narrowed, reducing version-pinning risk.

Module Summary

Field	Value
Module	github.com/modelcontextprotocol/go-sdk
Version	v1.6.1
Repository	https://github.com/modelcontextprotocol/go-sdk
Latest	v1.6.1 (v1.7.0-pre.1 available)
Files	~40 production + test
Reviewed	2026-06-25

References

• Docs: https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp
• Spec: (modelcontextprotocol.io/redacted)

Recommendations (Priority Order)

1. [HIGH] Fix context propagation through callSDKMethodWithReconnect → callSDKMethod for tool timeout enforcement
2. [MEDIUM] Add server.AddPrompt() registration for backend prompts to complete MCP capability parity
3. [MEDIUM] Add a canary test for server.AddTool vs sdk.AddTool behavior difference
4. [LOW] Monitor v1.7.0 changelog; audit version-pinned comments on upgrade
5. [LOW] Declare client capabilities on backend Connect calls

Next Steps

• File focused issue for context propagation fix (Recommendation Configure as a Go CLI tool #1)
• Review v1.7.0 changelog when stable
• Add canary test for AddTool bypass behavior

---

Generated by Go Fan · Run §28156334602

Generated by Go Fan · 1.7K AIC · ⊞ 34.5K · ◷

• expires on Jul 2, 2026, 8:24 AM UTC