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

[github-actions[bot]]

🐹 Go Fan Report — reviewing the most recently updated direct dependency in gh-aw.

Today's pick: github.com/modelcontextprotocol/go-sdk — selected because it's the most recently updated unreviewed direct dependency (v1.4.0 released 2026-02-27, just 5 days ago).

---

Module Overview

The official Go SDK for the [Model Context Protocol (MCP)]((modelcontextprotocol.io/redacted), the open standard that lets AI models connect to external data sources and tools. The SDK provides both server-side and client-side APIs, supporting stdio, HTTP (Streamable HTTP), and command transports.

gh-aw uses this SDK heavily — it's the backbone of the mcp-server command and the mcp inspect command.

---

Current Usage in gh-aw

• Files: 9 production files, 12 test files (21 total)
• Packages imported: mcp (server + client APIs), jsonrpc (error codes)
• Dual role: gh-aw acts as both an MCP server (exposing 8 tools) and an MCP client (to inspect external MCP servers in workflows)

Key APIs Used

API	Purpose
mcp.NewServer + mcp.AddTool[T]	Registers 8 typed tools (status, compile, logs, audit, mcp-inspect, add, update, fix)
mcp.StdioTransport	Default stdio MCP server mode
mcp.NewStreamableHTTPHandler	HTTP/SSE server mode (--port flag)
mcp.NewClient + mcp.CommandTransport	Client connecting to stdio MCP servers (mcp inspect)
mcp.StreamableClientTransport	Client connecting to HTTP MCP servers (mcp inspect)
jsonrpc.Error + error code constants	Structured error responses with code+message+data
mcp.ToolAnnotations	ReadOnlyHint, IdempotentHint, DestructiveHint, OpenWorldHint
mcp.Icon	Emoji tool icons

The usage is well-structured and idiomatic — generic AddTool[T] for type-safe handlers, correct transport selection, proper context management with per-operation timeouts.

---

Research Findings

Recent Updates (v1.4.0 — 2026-02-27)

1. DNS Rebinding Protection — Localhost servers now reject requests with non-localhost Host headers by default. This is a security win that is already active in gh-aw's HTTP server mode without any code changes needed.

2. No HTML Escaping in JSON — Switched from default encoding/json HTML escaping to no-escape marshaling by default. <, >, & in tool output will no longer be escaped to \u003c etc. This improves readability of JSON output from tools.

3. Sampling with Tools — Servers can now issue CreateMessageWithTools, clients can handle them. Not currently used by gh-aw, but relevant if future tools need AI assistance.

4. Client-side OAuth (experimental, build tag mcp_go_client_oauth) — For MCP client authentication flows. Could be relevant for the HTTP MCP server inspector when connecting to authenticated endpoints.

5. Extensions field in capabilities (SEP-2133) — Servers can now expose custom metadata in capabilities.

6. OSSF Scorecard 8.7 — The SDK project added security scanning; reassuring for a critical dependency.

7. Security fix: Case-sensitive JSON unmarshaling (backported to v1.3.1).

Best Practices from Maintainers

• Use mcp.AddTool[T] generic form for type-safe handlers ✅ (gh-aw does this)
• Set ListChanged: false when tools are static ✅ (gh-aw does this)
• Use DisableStandaloneSSE: true in client transport when you don't need server-initiated messages ✅ (correctly set in mcp_inspect_mcp.go)
• Handle ctx.Done() in long-running tools ✅ (gh-aw has pre-flight checks)
• Use SessionTimeout in HTTP server ✅ (2 hours, reasonable for MCP sessions)

---

Improvement Opportunities

🏃 Quick Wins

1. responseWriter missing WriteHeader override (mcp_server_http.go:26-29)

The HTTP logging middleware captures status codes for logging, but never overrides WriteHeader. This means every logged response shows status 200, even for 4xx/5xx errors from the MCP framework:

// Current — statusCode never updates for error responses:
type responseWriter struct {
    http.ResponseWriter
    statusCode int
}

// Missing method:
func (rw *responseWriter) WriteHeader(code int) {
    rw.statusCode = code
    rw.ResponseWriter.WriteHeader(code)
}

2. Duplicate client inspection code (mcp_inspect_mcp.go:131-221, 224-309)

connectStdioMCPServer and connectHTTPMCPServer share ~30 lines of identical ListTools/ListResources logic. Extracting to a queryServerCapabilities(ctx, session) helper would reduce the duplication and make it easier to add future capability queries (e.g., ListPrompts once the SDK supports it).

✨ Feature Opportunities

1. Extensions Capability Field (v1.4.0 SEP-2133)

The new extensions field in ServerCapabilities lets servers expose custom metadata that MCP Apps can read. gh-aw could expose:

// In mcp_server.go, inside ServerOptions:
Capabilities: &mcp.ServerCapabilities{
    Tools: &mcp.ToolCapabilities{ListChanged: false},
    // New in v1.4.0:
    Extensions: map[string]any{
        "gh-aw": map[string]any{
            "version": GetVersion(),
            "repo":    "github/gh-aw",
        },
    },
},

This makes gh-aw more discoverable for MCP-aware tooling.

2. Client-side OAuth for HTTP MCP Inspector

The StreamableClientTransport for HTTP inspection (mcp_inspect_mcp.go:238-256) uses a custom headerRoundTripper for auth headers. As client OAuth stabilizes in v1.5.0, the inspector could support OAuth flows for connecting to authenticated MCP endpoints in workflow frontmatter — enabling inspection of secured MCP servers without hardcoding tokens.

3. ListPrompts Support

When the MCP spec's Prompts capability sees wider adoption, the inspector could add session.ListPrompts alongside the existing ListTools/ListResources calls. The SDK currently supports this.

📐 Best Practice Alignment

1. Outer timeout context in connectToMCPServer

// connectToMCPServer creates a 30-second outer context...
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
// ...but connectStdioMCPServer immediately creates a tighter 10-second context
connectCtx, cancel := context.WithTimeout(ctx, MCPConnectTimeout) // 10s

The 30-second outer context acts as a safety cap. The relationship between the two timeouts should be documented so future contributors understand why both exist.

2. Consider slices.Contains for allowed tool check

In mcp_inspect_mcp.go:452, the code already uses slices.Contains correctly. Good — no action needed.

🔧 General Improvements

ctx.Err().Error() nil-safety — Several tool handlers pass ctx.Err().Error() as MCP error data in the cancellation check. There's a theoretical (though unlikely) race where ctx.Err() could return nil. A nil-safe pattern:

case <-ctx.Done():
    errMsg := "request cancelled"
    if ctxErr := ctx.Err(); ctxErr != nil {
        errMsg = ctxErr.Error()
    }
    return nil, nil, newMCPError(jsonrpc.CodeInternalError, "request cancelled", errMsg)

---

Recommendations

Priority order based on impact:

1. Fix WriteHeader in responseWriter (Quick Win, 3 lines) — Correct logging is needed for debugging HTTP transport issues
2. Extract queryServerCapabilities helper (Quick Win, refactor) — Reduces code duplication, easier to extend
3. Add extensions to ServerCapabilities (Feature, ~5 lines) — Low risk, improves discoverability
4. Document dual-timeout context pattern (Documentation) — Helps future contributors

---

Next Steps

• Fix responseWriter.WriteHeader override in mcp_server_http.go
• Extract shared ListTools/ListResources logic in mcp_inspect_mcp.go
• Evaluate extensions capability field for exposing gh-aw metadata
• Monitor v1.5.0 for stable client-side OAuth (expected end of March 2026)

---

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

References:

• go-sdk v1.4.0 release notes
• [MCP specification 2025-11-25]((modelcontextprotocol.io/redacted)
• §22659050095

AI generated by Go Fan · history

• expires on Mar 5, 2026, 7:19 AM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-03-05T07:19:58.583Z.

Closed by Workflow