Repository navigation
Description
πΉ Go Fan Report: modelcontextprotocol/go-sdk
Module Overview
github.com/modelcontextprotocol/go-sdk is the official Go SDK for the Model Context Protocol β the very foundation gh-aw-mcpg is built on. It provides both client and server implementations for MCP JSON-RPC 2.0, covering stdio, Streamable HTTP (2025-03-26 spec), and SSE (2024-11-05 spec) transports. This is arguably the most critical dependency in the project.
Version: v1.5.0 (current)
Current Usage in gh-aw-mcpg
The SDK permeates the entire codebase with 31 files importing it across internal/mcp/, internal/server/, internal/testutil/mcptest/, and test/integration/.
- Files: 31 files
- Import alias:
sdk "github.com/modelcontextprotocol/go-sdk/mcp"(consistent throughout) - Key APIs Used:
sdk.NewClient/sdk.NewServerβ gateway client+server creationsdk.CommandTransportβ stdio backend connectionssdk.StreamableClientTransport/sdk.SSEClientTransportβ HTTP backend transportssdk.NewStreamableHTTPHandlerβ serving MCP over HTTP to agentssdk.ClientSessionβ session method dispatch (ListTools, CallTool, etc.)sdk.ErrSessionMissingβ typed error sentinel for session expiry- All content types:
TextContent,ImageContent,AudioContent,EmbeddedResource sdk.Tool,sdk.Resource,sdk.Promptβ MCP primitive types
Research Findings
The codebase demonstrates deep, idiomatic usage of the SDK with several sophisticated patterns:
Notable Design Patterns
1. Transport Fallback Chain β The gateway implements a graceful degradation strategy for HTTP backends:
StreamableClientTransport (2025-03-26) β SSEClientTransport (deprecated) β Plain JSON-RPC POST
DisableStandaloneSSE: true on StreamableClientTransport prevents SDK-internal fallback, keeping the gateway in full control of transport selection.
2. registerToolWithoutValidation β Uses server.AddTool() (method form) instead of sdk.AddTool[In,Out]() (package function) to bypass JSON Schema validation for backends using draft-07 schemas. Combined with NormalizeInputSchema, this ensures all backend tools are visible to agents regardless of schema version divergence.
3. Three-Argument Handler Convention β Tool handlers use an internal func(ctx, req, state) (result, data, error) form extended from the SDK's native two-argument form. The extra parameters carry jq middleware pipeline state and DIFC write-sink data.
4. Per-Session Filtered Servers (routed mode) β createFilteredServer creates a sdk.Server per (backendID, sessionID) pair with only that backend's tools registered. LRU-cached with TTL=30min.
5. Reconnect-on-expiry β callSDKMethodWithReconnect detects sdk.ErrSessionMissing and rebuilds the client+session transparently, retrying once.
6. Pagination with Safety Guards β paginateAll wraps SDK list calls with cycle detection and a 100-page hard limit against misbehaving backends.
Best Practices Already In Place β
sdk.ErrSessionMissingchecked viaerrors.Is(typed sentinel, v1.5.0 pattern)sdk.ClientOptions.KeepAliveset for HTTP backends, 0 for stdiosdk.ServerOptions.Loggerintegrated vialogger.NewSlogLoggerWithHandlersdk.StreamableHTTPOptions.Stateless: falsefor stateful session handlingMaxRetries: -1onStreamableClientTransportto disable SDK-level retries (gateway owns retry logic)
Improvement Opportunities
π Quick Wins
-
Remove
isSessionNotFoundErrorstring fallback eventually β The function currently has two branches:errors.Is(err, sdk.ErrSessionMissing)(correct, future-proof) and a string-matching fallback for the plain JSON-RPC transport path. When the plain JSON-RPC fallback transport is retired or updated to use the SDK, the string-matching branch becomes dead code. Track this as tech debt. -
Document
MaxRetries: -1semantics β Add a comment that-1is the SDK's explicit "disable retries" sentinel value (non-obvious contract). The current comment says "Disable retries; reconnect logic is handled by the gateway" but doesn't mention why -1 specifically.
β¨ Feature Opportunities
-
SDK notification support β If
go-sdkadds first-classnotifications/messageandnotifications/progresssupport, the gateway could relay these to agents without custom JSON-RPC parsing. Watch the SDK changelog forNotifications()orOnNotification()additions. -
Streaming tool results β If the SDK evolves to support streaming
CallToolResultdelivery, the gateway's large-payload file-based fallback (payload.json) could potentially leverage native streaming instead. This is speculative but worth monitoring. -
server.AddResource()/server.AddPrompt()method variants β If the SDK adds non-validating method-form variants for resources and prompts (analogous toserver.AddTool()), the gateway could expose these endpoints with the same schema-flexibility guarantees.
π Best Practice Alignment
-
callSDKMethodstring dispatch β The switch statement on method name strings ("tools/list","tools/call", etc.) is the right pattern for a proxy gateway. No refactoring needed, but worth noting that adding new MCP methods (e.g.,completion/complete) requires adding cases here. -
ConvertToCallToolResultmanual JSON bridging β The manual decode of backend JSON intosdk.CallToolResultis necessary since the gateway proxies raw JSON from backends. The SDK doesn't offer a JSON-to-typed-result helper for this proxy pattern. The current multi-step approach (detect array β detect content field β decode content items) is correct.
π§ General Improvements
NormalizeInputSchemaand SDK version coupling β The comment intool_registry.gosays: "This distinction relies on internal SDK behaviour and must be re-verified on every SDK upgrade." Consider adding a test that verifiesserver.AddTool()accepts a schema without validating argument values, to catch this assumption breaking on SDK upgrades.
Recommendations
Priority 1 (Low effort, high safety):
- Add a regression test asserting
server.AddTool()does not validate argument values (guards against SDK upgrade breakage) - Document
MaxRetries: -1sentinel value explicitly
Priority 2 (Track for future):
- Monitor SDK changelog for notification support and streaming results
- Tag
isSessionNotFoundErrorstring fallback as tech debt with a// TODO: remove when plain JSON-RPC transport is retiredcomment
Next Steps
- Track SDK releases for v1.6.0+ features (notifications, streaming)
- Consider adding the SDK upgrade regression test described above
- The plain JSON-RPC fallback transport path could be a candidate for removal if all backends move to streamable/SSE
Generated by Go Fan πΉ
Module summary saved to: session files (specs/mods/ unavailable in this run β directory creation blocked by sandbox)
Run ID: Β§25097032457
Note
π Integrity filter blocked 15 items
The following items were blocked because they don't meet the GitHub integrity level.
- https://github.com/spf13/pflag/releases/tag/v1.0.10
get_latest_release: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved". - https://github.com/modelcontextprotocol/go-sdk/releases/tag/v1.5.0
get_latest_release: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved". - modelcontextprotocol/go-sdk@93a41b2
list_commits: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved". - https://github.com/santhosh-tekuri/jsonschema/releases/tag/v6.0.2
get_latest_release: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved". - https://github.com/ktr0731/go-mcp
search_repositories: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved". - https://github.com/ithena-one/mcp-governance-sdk
search_repositories: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved". - https://github.com/SetiabudiResearch/mcp-go-sdk
search_repositories: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved". - https://github.com/leefowlercu/go-mcp-registry
search_repositories: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved". - https://github.com/jeanlucthumm/modelcontextprotocol-go-sdk
search_repositories: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved". - https://github.com/x86ed/modelcontextprotocol-go-sdk
search_repositories: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved". - https://github.com/curioswitch/mcp-go-sdk-otel
search_repositories: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved". - https://github.com/ganawaj/mcp-transport-nats
search_repositories: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved". - https://github.com/kwasek404/warehouse-mcp
search_repositories: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved". - https://github.com/Deadlywolf712/godoc-mcp-plus
search_repositories: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved". - https://github.com/step-chen/atlassian-dc-mcp-go
search_repositories: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
To allow these resources, lower min-integrity in your GitHub frontmatter:
tools:
github:
min-integrity: approved # merged | approved | unapproved | noneGenerated by Go Fan Β· β 3.5M Β· β·
- expires on May 6, 2026, 7:56 AM UTC
Activity