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

[github-actions[bot]]

🐹 Go Fan Report: modelcontextprotocol/go-sdk

The most-recently-updated direct dependency in go.mod — fresh v1.5.0 just dropped on 2026-04-07!

---

Module Overview

github.com/modelcontextprotocol/go-sdk is the official Go SDK for the Model Context Protocol (MCP). It provides both server and client APIs for building and connecting to MCP servers over stdio or HTTP/SSE transports, with support for tools, resources, prompts, and OAuth.

---

Current Usage in gh-aw

This is one of the most extensively used modules in the codebase — it powers the entire gh aw mcp-server command.

• Files: 12 non-test Go files
• Import packages: mcp and jsonrpc
• Key APIs Used:
  • mcp.NewServer + mcp.AddTool (typed generics) — 12 tools registered
  • mcp.StdioTransport — default transport for mcp-server
  • mcp.NewStreamableHTTPHandler + StreamableHTTPOptions — HTTP mode with 2-hour session timeout
  • mcp.NewClient + mcp.CommandTransport — stdio client for mcp-inspect
  • mcp.StreamableClientTransport with DisableStandaloneSSE: true — efficient HTTP inspection
  • mcp.ToolAnnotations — ReadOnlyHint, IdempotentHint, OpenWorldHint on all tools
  • mcp.Icon — emoji icons on every tool
  • jsonrpc.Error — typed JSON-RPC error construction

The usage is idiomatic and well-structured. The typed generic handler pattern (func(ctx, *mcp.CallToolRequest, ArgsStruct)) is used consistently across all 12 tools, cancellation checks are at the top of every handler, and the HTTP inspector correctly uses DisableStandaloneSSE: true to avoid unnecessary server-sent events connections.

---

Research Findings

Recent Updates (v1.5.0 — 2026-04-07)

Change	Impact
Client-side OAuth stabilized — no build tag needed anymore	No immediate action needed; relevant if authenticated HTTP servers are added
Input validation errors → tool results (PR #863)	⚠️ Behavioral change: schema validation failures now return CallToolResult{IsError:true} instead of a JSON-RPC error
ioConn.protocolVersion mutex fix (PR #832)	Race condition fix; passive improvement
Parameterized Accept media types (PR #853)	Better MCP client compatibility
http.ResponseController for flushed writes (PR #870)	Reliability fix for HTTP transport
Enterprise Managed Authorization (auth/extauth)	Not relevant for current use case

Best Practices from the SDK

• Use DisableStandaloneSSE: true for inspection-only HTTP clients ✅ (already done)
• Use session.Close() with defer ✅ (already done)
• Supply ServerOptions.Logger for structured logging ✅ (already done)
• Use DestructiveHint on tools that modify state — see improvements below

---

Improvement Opportunities

🏃 Quick Wins

1. Add DestructiveHint to mutating tools

The fix, update, and add tools all modify the working tree (write files, apply codemods) but their mcp.ToolAnnotations don't set DestructiveHint: true. MCP clients use this hint to warn users before calling destructive tools.

// In registerFixTool, registerUpdateTool, registerAddTool:
Annotations: &mcp.ToolAnnotations{
    OpenWorldHint:   boolPtr(true),
    DestructiveHint: boolPtr(true),  // add this
},

2. Fix hardcoded client version in mcp_inspect_mcp.go

Both connectStdioMCPServer and connectHTTPMCPServer hardcode Version: "1.0.0":

// Current:
client := mcp.NewClient(&mcp.Implementation{Name: "gh-aw-inspector", Version: "1.0.0"}, ...)
// Better:
client := mcp.NewClient(&mcp.Implementation{Name: "gh-aw-inspector", Version: GetVersion()}, ...)

The server uses GetVersion() already — inspectors should too for traceability in MCP server logs.

3. Verify input validation error handling after v1.5.0

PR #863 changed: schema validation failures are now CallToolResult{IsError: true} instead of JSON-RPC errors. The project uses GenerateSchema[T]() for custom schemas and should check that mcp_server_tools_test.go covers invalid-input cases to confirm behavior is correct with this version.

✨ Feature Opportunities

Progress reporting for long-running tools

The logs and audit tools can run for minutes but provide no progress feedback. The SDK supports progress via ProgressToken:

// In the tool handler, check if client requested progress:
if token := req.Params.Meta.ProgressToken; token != nil {
    // send periodic progress updates
}

This would let MCP clients (e.g., Claude Code) show a spinner or progress percentage instead of a silent wait.

Pagination in mcp-inspect capability listing

session.ListTools and session.ListResources are called with empty params (no cursor). For MCP servers with many tools, paginated results are silently truncated. The fix:

// Accumulate all pages:
var allTools []*mcp.Tool
cursor := ""
for {
    result, err := session.ListTools(ctx, &mcp.ListToolsParams{Cursor: cursor})
    // ...
    allTools = append(allTools, result.Tools...)
    if result.NextCursor == "" { break }
    cursor = result.NextCursor
}

📐 Best Practice Alignment

Reduce duplication in mcp_inspect_mcp.go

connectStdioMCPServer and connectHTTPMCPServer share ~30 lines of identical capability-query logic (ListTools, ListResources with timeouts, error handling). Extract a queryMCPCapabilities(ctx, session) (*MCPServerInfo, error) helper to eliminate the duplication.

---

Recommendations (prioritized)

1. [Low effort / High value] Add DestructiveHint: true to fix, update, add tool annotations — 3-line change per tool, immediate benefit for MCP client UX
2. [Low effort] Replace hardcoded Version: "1.0.0" with GetVersion() in both inspector clients
3. [Medium effort] Add a regression test for invalid-input behavior with v1.5.0's tool-result error semantics
4. [Medium effort] Add cursor-based pagination in mcp-inspect capability listing
5. [Larger feature] Investigate progress token support for logs/audit tools

---

Next Steps

• Review the v1.5.0 changelog for any additional behavioral changes
• Check mcp_server_tools_test.go for invalid-input coverage to verify v1.5.0 compatibility
• Consider opening a tracking issue for DestructiveHint annotations

---

Module summary saved to: scratchpad/mods/go-sdk-mcp.md

References:

• §24768065345
• v1.5.0 Release Notes
• SDK Docs

Generated by Go Fan · ● 281.6K · ◷

• expires on Apr 23, 2026, 8:28 AM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Go Fan.

A newer discussion is available at Discussion #28013.