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

[github-actions]

Module Overview

github.com/modelcontextprotocol/go-sdk — the official Go SDK for the Model Context Protocol. Provides server-side (mcp.NewServer, mcp.AddTool) and client-side (mcp.NewClient) primitives plus stdio, in-memory, command, and streamable-HTTP transports. Selected today because it's the most recently pushed direct dependency (2026-08-18T07:42:59Z) in go.mod.

Current Usage in gh-aw

• Files: 33 files (mostly pkg/cli/mcp_*.go + tests), plus pkg/parser/mcp.go
• Version: v1.7.0 — this is the latest release (published 2026-07-28). Already fully up to date. 🎉
• Key roles:
  • Server (mcp_server.go): builds the gh aw MCP server with a static tool set (status, compile, logs, audit, audit-diff, checks, mcp-inspect, add, update, fix). ListChanged: false since tools never change — correctly sidesteps the new subscriptions/listen stream for a case that doesn't need it.
  • Transports: mcp.StdioTransport for CLI mode, mcp.NewStreamableHTTPHandler for --http mode, bound to 127.0.0.1 only, SessionTimeout: 2h.
  • Client: mcp.NewClient + CommandTransport/StreamableClientTransport/InMemoryTransports for the mcp inspect subcommand and end-to-end tests.
  • Middleware: AddReceivingMiddleware rewrites raw additionalProperties schema errors into "did you mean?" suggestions.
  • Progress reporting: notifyProgress() uses req.Params.GetProgressToken() + Session.NotifyProgress for long-running tools, no-oping cleanly when not requested.
  • Tool annotations: ReadOnlyHint/IdempotentHint/DestructiveHint/OpenWorldHint used consistently across every tool.

Research Findings

Recent Updates (v1.7.0, 2026-07-28)

Full support for MCP protocol revision 2026-07-28:

• Stateless/sessionless mode (SEP-2575) — initialize handshake replaced by per-request _meta + server/discover RPC.
• Multi-round-trip requests (MRTR, SEP-2322) — sampling/elicitation/roots server-initiated calls replaced by InputRequiredResult + retry.
• subscriptions/listen — unified stream replaces the four separate */list_changed notifications.
• Cacheable list results (ttlMs/cacheScope, SEP-2549).
• HTTP header standardization (Mcp-Method, x-mcp-header passthrough, SEP-2243).
• Formal deprecation of roots, sampling, and logging in the new revision (gh-aw uses none of these — nothing to migrate).
• Backward compatible: SDK auto-negotiates down to 2025-11-25 for stateful peers — exactly what gh-aw's HTTP server (no Stateless: true, 2h SessionTimeout) does today.
• 7 MCPGODEBUG escape-hatch flags for spec-compliance behavior changes, all removed in v1.9.0 — none needed by gh-aw, since its usage already matches the new defaults (e.g. bare-bool ReadOnlyHint/IdempotentHint, not *bool — this avoids needing hintomitempty=1).

Best Practices Observed

The codebase shows unusually deep SDK awareness:

• A comment in mcp_server.go notes "Schema caching is automatic in go-sdk v1.3.0+."
• A comment in mcp_tools_privileged.go explains why the timeout param deliberately has no static schema default — the SDK would fill it in before the handler sees the request, short-circuiting a per-request computed default. This is a real footgun avoided by understanding the SDK's default-application order.
• Loopback-only binding (127.0.0.1) as defense-in-depth alongside the SDK's own Host-header check, with an explicit comment noting the SDK dropped default cross-origin protection since v1.6.0.

Improvement Opportunities

🏃 Quick Wins

None required — dependency is pinned to latest, and usage patterns already reflect v1.7.0-era defaults rather than legacy MCPGODEBUG opt-outs.

✨ Feature Opportunities

• Stateless HTTP mode (StreamableHTTPOptions.Stateless = true) would opt the HTTP server into the new 2026-07-28 protocol revision. Given the deliberate 2h SessionTimeout (session affinity for long-running logs/audit calls), staying stateful is likely still the right call — flagging for awareness, not urging a change.
• Custom JSON-RPC method registration (new in v1.7.0, Convert all safe output JavaScript files (.cjs) to TypeScript with updated tests #956) — no current need identified, but available if gh-aw ever wants a lightweight non-tool RPC endpoint.
• x-mcp-header passthrough for logs/audit tool params (workflow_name, actor) — only relevant if the HTTP server is ever placed behind a reverse proxy; currently loopback-only so low priority.

📐 Best Practice Alignment

Already strong — correct annotation types, deliberate avoidance of premature schema defaults, in-code comments tracking SDK version-specific behavior.

🔧 General Improvements

No redundant or inefficient usage found. The middleware and progress-notification patterns are non-obvious, well-documented uses of the SDK that go beyond boilerplate.

Recommendations

1. No action needed this cycle — module is current and usage is idiomatic.
2. Keep the Stateless HTTP mode decision on the radar if/when the MCP ecosystem drops support for stateful sessions on newer protocol revisions.
3. Continue the practice of commenting why an SDK default is or isn't used (e.g. the timeout schema default) — it already prevented at least one subtle bug class.

Next Steps

• No immediate follow-up tasks required for this module.
• Revisit if a future go-sdk release changes stateful-session support or deprecates the legacy initialize handshake path entirely.

---

Generated by Go Fan
Module summary saved to: scratchpad/mods/go-sdk.md

Generated by 🐹 Go Fan · agent · 107.4 AIC · ⌖ 5.07 AIC · ⊞ 7.8K · ◷

• expires on Aug 19, 2026, 12:13 AM UTC-08:00

[github-actions]

Caution

agentic threat detected
Threat detection flagged this output in warn mode. Manual review is REQUIRED before any follow-up automation.

Details

Potential security threats were detected in the agent output.

Review the workflow run logs for details.

🍪 Issue Monster selected this for Copilot

I've identified this issue as a good candidate for automated resolution and requested assignment to the Copilot coding agent.

If assignment succeeds, the Copilot coding agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster · gpt54 · 2.05 AIC · ⌖ 11.5 AIC · ⊞ 8.8K · ◷

[github-actions]

🍪 Issue Monster selected this for Copilot

I've identified this issue as a good candidate for automated resolution and requested assignment to the Copilot coding agent.

If assignment succeeds, the Copilot coding agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster · gpt54 · 1.02 AIC · ⌖ 8.44 AIC · ⊞ 9.6K · ◷