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

[github-actions]

Module Overview

github.com/modelcontextprotocol/go-sdk (v1.6.1) is the official Go SDK for MCP — the foundation of gh-aw-mcpg. Every MCP connection, session, tool dispatch, and transport negotiation runs through it.

Current Usage

• 41 Go files import the SDK (17 production + 24 test files) across internal/mcp/, internal/server/, internal/middleware/, internal/testutil/mcptest/
• Imported uniformly as sdk "github.com/modelcontextprotocol/go-sdk/mcp"

Key APIs Used

API	Package	Purpose
sdk.Client / sdk.ClientSession	internal/mcp/	Backend MCP connections
sdk.Server / sdk.NewServer	internal/server/	Front-facing MCP server
sdk.StreamableClientTransport	internal/mcp/http_transport.go	HTTP 2025-03-26 spec transport
sdk.SSEClientTransport	internal/mcp/http_transport.go	SSE 2024-11-05 spec transport
sdk.CommandTransport	internal/mcp/connection.go	Stdio for Docker container backends
sdk.NewStreamableHTTPHandler	internal/server/middleware.go	Stateful session management
sdk.NewInMemoryTransports	tests	Zero-dep paired transports for testing
sdk.ErrSessionMissing	internal/mcp/http_transport.go	Session expiry sentinel (v1.5.0+)
sdk.ToolAnnotations	internal/server/unified.go	Tool metadata passthrough

Usage Patterns

1. Transport fallback chain: streamable HTTP → SSE → plain JSON-RPC
2. Custom reconnect: streamableMaxRetries = -1 disables SDK retries; gateway owns reconnects
3. Schema bypass: Server.AddTool (method, not package-level func) skips argument validation, allowing draft-07 schemas from backends
4. slog bridge: custom logger bridges to SDK's *slog.Logger
5. Canary tests: TestMaxRetriesSentinelCanary + TestArgumentValidationBypassCanary guard SDK upgrades

Improvement Opportunities

🏃 Quick Wins

1. ToolAnnotations dropped in routed mode — createFilteredServer constructs &sdk.Tool{} without Annotations: toolInfo.Annotations. Clients on /mcp/{serverID} lose annotation hints (readOnly, destructive) visible on the unified endpoint. Fix: add Annotations: toolInfo.Annotations in routed.go:122.

2. Comment clarity in http_transport.go:117 — the comment says sdk.ErrSessionMissing is "matched by backend error text instead" but doesn't explain why (plain JSON-RPC uses a custom HTTP client that doesn't surface SDK errors). A clearer comment would help future maintainers.

✨ Feature Opportunities

1. Progress notification forwarding — go-sdk supports notifications/progress. Backends can emit progress during long tool calls; the gateway doesn't forward these to clients today.

2. Typed system tool args — sys___init and sys___list_servers have fixed schemas. They could use sdk.AddTool[SysInitArgs, ...] (generics path) for compile-time argument safety, removing the manual json.Unmarshal.

3. Centralize sdk.Implementation — newSDKServer and newMCPClient both construct sdk.Implementation{Name: ..., Version: version.Get()} independently. A shared helper would be a single source of truth.

📐 Best Practice Alignment

• ✅ sdk.NewInMemoryTransports() for unit tests — already used
• ✅ DisableStandaloneSSE: true for request-response mode — correctly set
• ✅ StreamableHTTPOptions.SessionTimeout aligned with gateway session config
• ⚠️ Upgrade gate canaries exist but aren't documented in AGENTS.md — add an ## SDK Upgrade Process section

Module Summary

Field	Value
Module	github.com/modelcontextprotocol/go-sdk
Version	v1.6.1
Repository	https://github.com/modelcontextprotocol/go-sdk
MCP Specs	2025-03-26 (streamable), 2024-11-05 (SSE), stdio
Usage Depth	Core — 41 files, 5 packages
Last Reviewed	2026-07-03

Recommendations (Priority Order)

1. [High] Fix ToolAnnotations in createFilteredServer — add Annotations: toolInfo.Annotations to the &sdk.Tool{} in routed.go:122
2. [Medium] Document SDK upgrade gate — add ## SDK Upgrade Process to AGENTS.md referencing the two canary tests
3. [Low] Centralize sdk.Implementation construction — single newSDKImplementation() helper
4. [Future] Evaluate progress notification forwarding for long tool calls

Next Steps

• Fix ToolAnnotations drop in routed mode (internal/server/routed.go:122)
• Add SDK upgrade gate docs to AGENTS.md
• Centralize sdk.Implementation construction
• Track go-sdk v1.7.x+ for progress/roots forwarding APIs

---

Generated by Go Fan 🐹 — §28647220857

References:

• https://github.com/modelcontextprotocol/go-sdk
• (modelcontextprotocol.io/redacted)

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• awmgmcpg

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "awmgmcpg"

See Network Configuration for more information.

Generated by Go Fan · 192.2 AIC · ⊞ 6.8K · ◷

• expires on Jul 10, 2026, 8:16 AM UTC