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

[github-actions[bot]]

The Go Fan is here! Today's deep dive focuses on github.com/modelcontextprotocol/go-sdk — the most recently updated direct dependency in this project (pushed yesterday, 2026-02-18). This is a particularly exciting module because gh-aw is, at its core, an MCP server — so this SDK is central to everything.

---

Module Overview

The official Go SDK for Model Context Protocol provides both server and client implementations for building MCP-compliant services. It exposes tools, resources, and roots over stdio or HTTP (SSE/streamable) transports. Maintained in collaboration with Google, it's actively developed with frequent releases.

Current version: v1.3.0 | Latest: v1.3.1 (released yesterday!)

---

Current Usage in gh-aw

• Files: 15 files (1 main source, 1 parser source, 13 test files)
• Import count: ~100 occurrences across production + test code
• Key APIs Used:
  • mcp.NewServer() + mcp.AddTool() — 8 tools registered (status, compile, logs, audit, mcp-inspect, add, update, fix)
  • mcp.StdioTransport{} + mcp.NewStreamableHTTPHandler() — dual transport support
  • mcp.NewClient() + mcp.CommandTransport + mcp.StreamableClientTransport — inspector client
  • jsonrpc.Error{Code, Message, Data} — structured error responses
  • mcp.Tool.Icons (SEP-973), mcp.ServerOptions.Capabilities (v1.2.0), elicitation defaults (SEP-1024)

The project makes excellent use of the typed mcp.AddTool[T]() generic API pattern, which automatically derives JSON schemas from Go struct types. The code is well-integrated with proper timeouts, logger wiring, and transport selection logic.

---

Research Findings

v1.3.1 — Security Patch (released 2026-02-18)

This is a patch release for v1.3.0 containing a cherry-pick security fix for issue #805.

The issue: Go's standard library JSON decoder allows case-insensitive matches to struct field names (or json tags). This was exploited as a security concern in MCP message parsing.

The fix: Switched the JSON decoder to github.com/segmentio/encoding which provides case-sensitive matching.

Impact on gh-aw: The project is running v1.3.0 which lacks this fix. Since gh-aw is an MCP server that receives JSON-RPC messages from external MCP clients, upgrading to v1.3.1 is recommended for security hardening.

v1.3.0 — Schema Caching & Enhanced Logging

• Schema caching: Avoids repeated reflection for stateless server deployments (significant perf improvement). The code already has a comment acknowledging this: // Note: Schema caching is automatic in go-sdk v1.3.0+.
• DisableListening option for StreamableClientTransport — useful for query-only clients
• Logger in ClientOptions — replaces deprecated logger field (already used in project)
• GetError/SetError methods exported for jsonrpc.Error
• Nightly conformance tests added to ensure spec compliance
• Race condition fix in logging

v1.2.0 — 2025-11-25 Spec Support

Already leveraged by gh-aw:

• SEP-973 icons: mcp.Icon{Source: "emoji"} on all tools ✅
• SEP-1024 elicitation defaults: AddSchemaDefault() on compile/logs tools ✅
• Capabilities field on ServerOptions: Used in createMCPServer() ✅
• jsonrpc.Error sentinels: CodeInvalidRequest, CodeInternalError, CodeInvalidParams ✅
• OAuth 2.0 Protected Resource Metadata: Not currently used (gh-aw uses actor-based RBAC)
• UserID in TokenInfo: Not currently used (gh-aw uses env-based actor)

---

Improvement Opportunities

🚨 Critical — Security Patch

Upgrade to v1.3.1 immediately. This is a security fix for case-insensitive JSON unmarshaling. As an MCP server receiving external JSON-RPC messages, gh-aw should be on the patched version.

go get github.com/modelcontextprotocol/go-sdk@v1.3.1
go mod tidy

🏃 Quick Wins

1. Refactor duplicate root extraction code

connectStdioMCPServer() and connectHTTPMCPServer() in mcp_inspect_mcp.go contain identical root URI extraction logic (~20 lines each). This is a straightforward refactor:

func extractRootsFromResources(resources []*mcp.Resource) []*mcp.Root {
    var roots []*mcp.Root
    for _, resource := range resources {
        if strings.Contains(resource.URI, "://") {
            // ... existing heuristic logic ...
        }
    }
    return roots
}

2. Add Logger to StreamableClientTransport in inspector

connectHTTPMCPServer() sets Logger on ClientOptions but not on StreamableClientTransport. The transport itself can log connection-level events:

transport := &mcp.StreamableClientTransport{
    Endpoint:   config.URL,
    Logger:     logger.NewSlogLoggerWithHandler(mcpInspectServerLog),
    HTTPClient: ...,
}

3. Use DisableListening: true in inspector

The inspector client only queries capabilities — it never needs to receive server-initiated messages. Setting DisableListening: true on StreamableClientTransport for the HTTP inspector reduces resource usage:

transport := &mcp.StreamableClientTransport{
    Endpoint:        config.URL,
    DisableListening: true,
}

✨ Feature Opportunities

4. Add OutputSchema to MCP server tools

v1.2.0+ supports structured OutputSchema on tools. The inspect display code in displayDetailedToolInfo() already handles OutputSchema, but no tools in mcp_server.go define output schemas. Adding output schemas for status, compile, logs, and audit would:

• Help LLM clients understand response structure before calling
• Enable better response validation
• Improve documentation auto-generation

Example for the status tool:

type statusResult struct {
    Workflow  string `json:"workflow"`
    Agent     string `json:"agent"`
    Compiled  string `json:"compiled"`
    Status    string `json:"status"`
    TimeRemaining string `json:"time_remaining,omitempty"`
}
outputSchema, _ := GenerateSchema[[]statusResult]()

mcp.AddTool(server, &mcp.Tool{
    Name:         "status",
    OutputSchema: outputSchema,
    ...
}, handler)

5. Direct ListRoots instead of resource heuristic

The current root extraction uses a heuristic (parsing :// from resource URIs). The MCP spec supports direct roots querying. Consider using session.ListRoots() if available in the SDK for more accurate root discovery.

📐 Best Practice Alignment

6. Add ToolAnnotations to server tools

The displayDetailedToolInfo() function already renders tool annotations (ReadOnlyHint, IdempotentHint, DestructiveHint, OpenWorldHint), but the MCP server tools don't define Annotations. Adding them improves LLM understanding:

mcp.AddTool(server, &mcp.Tool{
    Name: "status",
    Annotations: &mcp.ToolAnnotations{
        ReadOnlyHint:  true,
        OpenWorldHint: false, // reads local workflow state only
    },
    ...
}, handler)

Suggested annotations:

Tool	ReadOnly	Idempotent	Destructive	OpenWorld
status	✅	✅	—	❌
compile	❌	✅	❌	❌
logs	✅	✅	—	✅
audit	✅	✅	—	✅
mcp-inspect	✅	✅	—	✅
add	❌	❌	—	✅
update	❌	❌	—	✅
fix	❌	✅	❌	❌

7. Elicitation defaults for mcp-inspect

The mcp-inspect tool has no elicitation defaults. Consider if check-secrets: true could be an elicitation default to surface this option to LLM clients.

---

Recommendations (Prioritized)

1. [SECURITY] Upgrade to v1.3.1 — go get github.com/modelcontextprotocol/go-sdk@v1.3.1
2. [QUICK WIN] Refactor duplicate root extraction — DRY cleanup in mcp_inspect_mcp.go
3. [FEATURE] Add OutputSchema to tools — Start with status and compile as they have well-defined JSON structures
4. [BEST PRACTICE] Add ToolAnnotations — Improve LLM understanding of tool behavior
5. [QUICK WIN] DisableListening on inspector HTTP transport — Reduce resource usage

---

Overall Assessment

The go-sdk integration in gh-aw is well-implemented and up-to-date with the v1.2.0/v1.3.0 feature set. The team has already adopted icons (SEP-973), elicitation defaults (SEP-1024), the Capabilities API, and typed tool handlers. The main action item is the v1.3.1 security patch, followed by nice-to-have improvements around output schemas and tool annotations.

Next Steps:

• go get github.com/modelcontextprotocol/go-sdk@v1.3.1 && go mod tidy
• Add OutputSchema to status tool (best structured output)
• Add ToolAnnotations to all 8 server tools
• Refactor extractRootsFromResources() helper

---

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

References: §22172332637

AI generated by Go Fan

• expires on Feb 26, 2026, 7:27 AM UTC

[pelikhan]

/plan