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

[github-actions[bot]]

Module Overview

github.com/modelcontextprotocol/go-sdk is the official Go SDK for the Model Context Protocol (MCP) — an open standard that enables AI models to interact with tools and data sources via structured JSON-RPC 2.0. This is a foundational dependency for gh-aw's entire MCP server surface.

Why reviewed today: This module had a commit at 07:56 UTC on 2026-04-28 (today), making it the most recently-updated direct dependency in the repo.

---

Current Usage in gh-aw

The SDK is used across 13 non-test source files spanning both server and client roles:

• Files: 13 source files, 10 test files
• Import count: 26 total imports (mcp package: 20, jsonrpc package: 6)
• Key APIs used: mcp.NewServer, mcp.AddTool (generic), mcp.StdioTransport, mcp.NewStreamableHTTPHandler, mcp.NewClient, mcp.CommandTransport, mcp.StreamableClientTransport, jsonrpc.Error

Server-side (pkg/cli/mcp_server*.go, mcp_tools_*.go): Exposes 9 gh-aw commands as MCP tools with full ToolAnnotations (ReadOnly, Idempotent, Destructive, OpenWorld hints), emoji icons, and typed input structs.

Client-side (pkg/cli/mcp_inspect_mcp.go): Connects to external MCP servers (stdio and HTTP) declared in workflow files to inspect their tool/resource/root inventory.

Parser (pkg/parser/mcp.go): Uses mcp.Tool, mcp.Resource, mcp.Root as data types in server inspection results.

---

Research Findings

The module is under active daily development (10 commits in the last 7 days). v1.5.0 was released 2026-04-07.

Recent Updates (v1.5.0)

• Client OAuth stabilized — no longer requires mcp_go_client_oauth build tag; standard backward compatibility now applies
• Input validation as tool results — validation errors now return as CallToolResult (not JSON-RPC protocol errors), giving callers consistent structured output
• Keepalive ping gracefully handles method-not-found — peers that don't implement ping no longer drop sessions
• mcp.Tool.OutputSchema — tools can now document their return shape
• Enterprise Managed Authorization — new auth/extauth package
• http.ResponseController flush — ensures SSE writes are properly flushed
• Cross-origin protection removed by default — previously required opt-out

Best Practices from SDK Maintainers

• Use mcp.AddTool generic form (project already does this correctly)
• Set ToolAnnotations hints to help clients make safe decisions (project does this correctly)
• Return domain errors as CallToolResult (not jsonrpc.Error) so LLMs receive consistent JSON
• Use progress tokens for long-running tools
• Paginate ListTools/ListResources via NextCursor

---

Improvement Opportunities

🏃 Quick Wins

1. Dead code: http.DefaultTransport == nil guard (mcp_inspect_mcp.go:249)
   http.DefaultTransport is never nil in the standard library. The nil-guard around creating a fallback http.Transport{} is unreachable and can be removed.

2. Add Annotations.Title to tool registrations
   The mcp.ToolAnnotations.Title field provides a human-readable display name separate from tool.Name. None of the 9 registered tools set this. MCP client UIs (e.g., Claude Desktop) use this for cleaner display. Example: Title: "Compile Workflows" for the compile tool.

3. OutputSchema for JSON-returning tools
   status, compile, checks, audit, and logs all return well-defined JSON structures. Adding mcp.Tool{OutputSchema: ...} documents the response shape for MCP client tooling and enables validation. The project already uses GenerateSchema[T]() for inputs — the same mechanism applies to outputs.

✨ Feature Opportunities

4. Progress reporting for logs and audit tools
   These tools can run for minutes (up to the configured timeout). The SDK supports emitting progress notifications via req.Params.Meta.ProgressToken. Callers that pass a progress token (like Claude Desktop) would see live download progress instead of a hung tool call.

   // In the tool handler, after acquiring req:
   if token := req.Params.Meta.ProgressToken; token != nil {
       req.ReportProgress(ctx, &mcp.ProgressParams{
           ProgressToken: token,
           Progress:      0.5,
           Total:         floatPtr(1.0),
           Message:       "Downloading logs...",
       })
   }

5. Expose workflow status as an MCP Resource
   The status tool returns a list of workflow states — a natural fit for an MCP Resource that clients can subscribe to for updates. Resources support URI-based access and change notifications, enabling richer integration with AI agents.

📐 Best Practice Alignment

6. Error protocol consistency
   Post-v1.5.0, input validation errors should be tool results (not JSON-RPC errors). The project is partially consistent: validateMCPWorkflowName returns a CallToolResult, but missing required params like empty pr_number or run_ids_or_urls return jsonrpc.Error. The distinction: protocol errors (malformed JSON-RPC) vs. domain errors (user provided bad input). Domain errors should always be CallToolResult for consistent LLM consumption.

7. createMCPServer silent failure
   When registerCompileTool or registerLogsTool fail (schema generation error), createMCPServer returns a partially-registered server. The caller (runMCPServer) gets a server with zero tools silently. Returning an error would let the process exit clearly rather than start an empty server.

8. Inspector deduplication
   connectStdioMCPServer and connectHTTPMCPServer share ~80% logic: connect → ListTools → ListResources → extractRoots. Extracting a shared queryServerCapabilities(ctx, session) helper would reduce copy-paste and make pagination fixes apply to both transports.

9. Pagination in ListTools/ListResources
   Both inspector functions call ListTools / ListResources once without following NextCursor. Servers with more tools than the default page size will appear truncated with no warning. A simple loop until NextCursor == "" would fix this.

---

Recommendations (Prioritized)

Priority	Action	Effort
P0	Fix dead code http.DefaultTransport == nil	2-line delete
P1	Normalize domain errors to tool results (not jsonrpc.Error)	Medium
P1	Add OutputSchema to JSON-returning tools	Medium
P2	Add Annotations.Title to all 9 tools	Low
P2	Paginate ListTools/ListResources in inspector	Low
P3	Progress reporting in logs/audit	Medium
P3	Extract queryServerCapabilities shared helper	Low
P4	MCP Resource for workflow status	High

---

Next Steps

• Remove dead http.DefaultTransport == nil guard in connectHTTPMCPServer
• Audit all newMCPError call sites — categorize as protocol vs. domain errors and convert domain ones to tool results
• Add Tool.OutputSchema for compile, checks, audit tools
• Add Annotations.Title to all tool registrations
• Add pagination loop to connectStdioMCPServer / connectHTTPMCPServer

---

Module summary saved to: scratchpad/mods/go-sdk.md
Workflow run: §25042851927

References:

• go-sdk v1.5.0 release notes
• pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp

Generated by Go Fan · ● 367.7K · ◷

• expires on Apr 29, 2026, 8:48 AM UTC

[github-actions[bot]]

💥 POW! 🦸 The Smoke Test Agent was HERE, and it was MAGNIFICENT!

⚡ WHOOSH ⚡ Claude engine blazing at full power — Run 25044466924 complete!

🔥 BAM! 18 tests fired, all systems NOMINAL! The agentic hero swept through every MCP tool, Serena symbols crackled, Playwright soared like a cape-billowing superhero over https://github.com, and Tavily search cut through the web like a laser beam!

ZAP! 💫 The smoke has cleared, and GitHub Agentic Workflows stand TRIUMPHANT!

"With great workflows comes great responsibility." — Claude, probably

💥 [THE END] — Illustrated by Smoke Claude · ● 211K · ◷

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-04-29T08:48:21.786Z.

Closed by Workflow