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

[github-actions[bot]]

Selected today because: Most recently updated direct dependency — v1.3.1 released 2026-02-18 with a security fix.

Module Overview

github.com/modelcontextprotocol/go-sdk is the official Go implementation of the Model Context Protocol (MCP), the open standard for connecting AI models to tools and data sources. It is the backbone of gh-aw's MCP server, providing type-safe tool registration, multiple transport mechanisms (stdio, HTTP/SSE), and client-side MCP server inspection.

Version in use: v1.3.1 (latest — released 2026-02-18)

---

Current Usage in gh-aw

The module is used across 9 production files and 14 test files, split between two packages:

Package	Role
mcp	Server/client construction, tool registration, transports
jsonrpc	Error types and standard error codes

Files: pkg/cli/mcp_server.go, mcp_server_command.go, mcp_server_http.go, mcp_server_helpers.go, mcp_tools_readonly.go, mcp_tools_privileged.go, mcp_tools_management.go, mcp_inspect_mcp.go, pkg/parser/mcp.go

Key APIs in use:

• mcp.NewServer / mcp.AddTool (generic, type-safe) — 8 tools registered
• mcp.ToolAnnotations with ReadOnlyHint, IdempotentHint, DestructiveHint, OpenWorldHint
• mcp.StdioTransport + mcp.NewStreamableHTTPHandler — dual transport support
• mcp.NewClient + mcp.CommandTransport / mcp.StreamableClientTransport — client-side inspector
• mcp.Icon with emoji sources on all tools
• jsonrpc.Error with CodeInternalError, CodeInvalidParams, CodeInvalidRequest
• Elicitation defaults via AddSchemaDefault (compile: strict=true, logs: count=100, timeout=50)

---

Research Findings

Recent Release History (v1.0.0 → v1.3.1)

Version	Date	Highlights
v1.3.1	2026-02-18	Security fix: case-sensitive JSON unmarshaling (CVE-like: arbitrary struct field matching)
v1.3.0	2026-02-09	Schema caching, DisableListening for client transport, Logger in ClientOptions, exported GetError/SetError
v1.2.0	2025-12-22	2025-11-25 spec: icons, elicitation, tool name validation, OAuth2 metadata
v1.1.0	2025-10-30	Significant MCP spec coverage improvements
v1.0.0	2025-09-30	Initial stable release

Recent Updates Worth Noting

Security patch (v1.3.1): The SDK's JSON decoder previously allowed case-insensitive struct field matching, which could be exploited to bypass server-side validation. The fix switches to segmentio/encoding for case-sensitive decoding. gh-aw is already on v1.3.1 — no action required.

Schema caching (v1.3.0): Automatic caching of JSON schemas to avoid repeated reflection. The code in mcp_server.go already has a comment acknowledging this: "Schema caching is automatic in go-sdk v1.3.0+ (eliminates repeated reflection overhead)". Well noted.

DisableListening (v1.3.0): A new option was added to StreamableClientTransport that prevents the client from listening for any server-initiated messages at all. More on this below.

Best Practices from Maintainers

• Tool annotations (ReadOnlyHint, OpenWorldHint, etc.) are core to the MCP 2025-11-05 spec and help clients make better decisions about tool invocation. ✅ gh-aw does this correctly.
• Elicitation defaults signal preferred parameter values to LLM clients. ✅ Used for strict, count, timeout.
• Contexts should be propagated correctly through client operations for proper cancellation.

---

Improvement Opportunities

🏃 Quick Wins

1. Adopt DisableListening: true in the HTTP MCP inspector

mcp_inspect_mcp.go:242 uses DisableStandaloneSSE: true on StreamableClientTransport. v1.3.0 added DisableListening, which more precisely expresses intent for the inspector: it connects, queries capabilities, and leaves — no server push needed at all.

// Current (mcp_inspect_mcp.go)
transport := &mcp.StreamableClientTransport{
    Endpoint:             config.URL,
    DisableStandaloneSSE: true,
}

// Opportunity: also set DisableListening for v1.3.0+
transport := &mcp.StreamableClientTransport{
    Endpoint:         config.URL,
    DisableListening: true,
}

2. Propagate parent context in checkActorPermission

In mcp_server_helpers.go, the actor permission check creates a fresh context.Background() context:

// Current: ignores tool handler's cancellation context
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
permission, err := queryActorRole(ctx, actor, repo)

If a tool handler's context is cancelled (e.g., client disconnects), this permission check still runs for up to 5 seconds against the GitHub API. Using the parent context would respect request lifecycle:

// Better: inherits cancellation from the calling handler
permCtx, cancel := context.WithTimeout(callerCtx, 5*time.Second)
defer cancel()
permission, err := queryActorRole(permCtx, actor, repo)

3. Release sub-contexts promptly in the MCP inspector

In connectStdioMCPServer and connectHTTPMCPServer, three WithTimeout contexts are created sequentially and cancelled via defer. Since they're used one-at-a-time, calling cancel() immediately after each operation (rather than deferring) would release resources sooner:

// Current pattern — all three deferred to function return
listToolsCtx, cancel := context.WithTimeout(ctx, MCPOperationTimeout)
defer cancel()
toolsResult, err := session.ListTools(listToolsCtx, ...)

// Better — cancel as soon as the operation is done
listToolsCtx, cancel := context.WithTimeout(ctx, MCPOperationTimeout)
toolsResult, err := session.ListTools(listToolsCtx, ...)
cancel()

✨ Feature Opportunities

1. Structured Tool Output via OutputSchema

The MCP 2025-11-25 spec supports typed output schemas via mcp.Tool.OutputSchema. The status, logs, and audit tools all return structured JSON — declaring OutputSchema would allow LLM clients to understand and validate the tool's output format. The project already uses jsonschema-go for input schema generation; the same pattern could extend to outputs.

2. Consider a newMCPError helper

There are 30+ &jsonrpc.Error{Code: ..., Message: ..., Data: ...} literals scattered across tool files. A small helper function would reduce repetition and make error patterns more consistent:

func newMCPError(code int, msg string, data any) error {
    return &jsonrpc.Error{Code: code, Message: msg, Data: mcpErrorData(data)}
}

📐 Best Practice Alignment

Practice	Status	Notes
Tool annotations (read-only, idempotent, etc.)	✅	All 8 tools properly annotated
Elicitation defaults	✅	Used for compile, logs tools
Logger in ClientOptions	✅	Already using v1.3.0 ClientOptions.Logger
On latest version with security fix	✅	v1.3.1
DisableListening for read-only inspector	💡	New v1.3.0 option not yet adopted
Context propagation in permission check	💡	Uses context.Background() instead of caller ctx
Prompt cancel() of sequential sub-contexts	💡	Minor cleanup opportunity

---

Recommendations

1. Adopt DisableListening: true in the HTTP inspector's StreamableClientTransport — simple one-line change, more semantically correct.
2. Fix context propagation in checkActorPermission — pass the tool handler context (with a 5s cap) to respect request lifecycle.
3. Consider OutputSchema for the structured-output tools (status, audit, logs) — aligns with MCP 2025-11-25 spec and improves LLM integration.
4. Track GetError/SetError methods exported in v1.3.0 — may simplify some error handling patterns in future cleanup.

---

Next Steps

• Evaluate DisableListening vs DisableStandaloneSSE behavior in the HTTP inspector
• Audit checkActorPermission context propagation
• Prototype OutputSchema for the audit tool as a proof-of-concept

---

Module summary saved to: scratchpad/mods/go-sdk.md
Workflow run: §22340699977
Date: 2026-02-24

AI generated by Go Fan

• expires on Feb 25, 2026, 7:29 AM UTC

[github-actions[bot]]

🤖 Beep boop! The smoke test agent was here! 🚀

Just stopping by to say: all systems nominal, circuits are humming, and the coffee machine is still operational. The robots are taking over... the testing pipeline, at least! 🦾

[automated smoke test visit - run 22340962753]

📰 BREAKING: Report filed by Smoke Copilot

[github-actions[bot]]

🎉 Greetings from the Copilot Smoke Test Bot! 🎉

I've just completed a full smoke test run and I'm pleased to report the automation machinery is purring like a well-oiled robot! 🤖

Here's my haiku tribute to this occasion:

Tests run and pass green
Automation never sleeps
Code flows endlessly

Stay excellent, humans! 🚀 [run 22340962753]

📰 BREAKING: Report filed by Smoke Copilot