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

[github-actions[bot]]

🐹 Go Fan Report: modelcontextprotocol/go-sdk

Selected because: Most recently pushed direct dependency (2026-04-20T15:09:49Z — yesterday!) · First run, no prior reviews

---

Module Overview

github.com/modelcontextprotocol/go-sdk is the official Go SDK for the Model Context Protocol, maintained in collaboration with Google. It provides both server and client APIs for building MCP-compatible tools, agents, and integrations. The SDK implements the full MCP spec including tools, resources, roots, sampling, and OAuth.

• Stars: 4,402 | Forks: 412 | OSSF Scorecard: 8.7/10
• License: Apache 2.0 (new contributions) / MIT (existing code)
• Version in use: v1.5.0 ✅ LATEST (released 2026-04-07, 2 weeks ago)

---

Current Usage in gh-aw

gh-aw is a heavy, sophisticated user of this SDK — it's both a server (exposing gh aw commands as MCP tools) and a client (inspecting external MCP servers).

• Files: 10 source files, 14 test files
• Import Count: Both mcp and jsonrpc sub-packages used
• Server transport: stdio (default) + HTTP/SSE (--port flag)
• Client transport: CommandTransport (stdio) + StreamableClientTransport (HTTP)

Key APIs Used:

API	Where	Purpose
mcp.NewServer	mcp_server.go	Create the tool server
mcp.AddTool (typed)	all tool files	Register 9 tools with struct-based schemas
mcp.StdioTransport	mcp_server_command.go	stdio mode
mcp.NewStreamableHTTPHandler	mcp_server_http.go	HTTP/SSE mode
mcp.NewClient	mcp_inspect_mcp.go	MCP inspection client
mcp.CommandTransport	mcp_inspect_mcp.go	stdio server inspection
mcp.StreamableClientTransport	mcp_inspect_mcp.go	HTTP server inspection
mcp.ToolAnnotations	all tool files	ReadOnlyHint, IdempotentHint, etc.
mcp.Icon	all tool files	Emoji icons per tool
jsonrpc.Error + codes	mcp_error.go, tools	Structured error responses

---

Research Findings

Recent Updates (v1.4.0 → v1.5.0)

Feature	Version	Relevance to gh-aw
Stabilized client OAuth	v1.5.0	Not used, but available
Enterprise Managed Authorization	v1.5.0	Not used
CreateMessageWithTools (sampling)	v1.5.0	Not used
Input validation → tool results (not JSON-RPC errors)	v1.5.0	SDK handles schema-level errors automatically now
Cross-origin + Content-Type verification	v1.4.1	Automatic in NewStreamableHTTPHandler
DNS rebinding protection	v1.4.0	Automatic for localhost servers
MemoryEventStore empty chunk fix	v1.5.0	Benefits SSE server
http.ResponseController flush	v1.5.0	Benefits HTTP server
Extensions field in capabilities	v1.4.0	Not yet used

Best Practices from Maintainers

• Use typed struct parameters in mcp.AddTool for automatic schema generation ✅ (gh-aw does this)
• Defer session.Close() after client.Connect ✅ (gh-aw does this)
• Use context timeouts for all client operations ✅ (gh-aw does this with MCPConnectTimeout/MCPOperationTimeout)
• Set DisableStandaloneSSE: true for short-lived inspection clients ✅ (gh-aw does this)
• Use IsError: true in CallToolResult for errors-as-content ✅ (gh-aw does this for audit/audit-diff)

---

Improvement Opportunities

🏃 Quick Wins

1. Paginate ListTools/ListResources in the inspector

The connectStdioMCPServer and connectHTTPMCPServer functions both call:

toolsResult, err := session.ListTools(listToolsCtx, &mcp.ListToolsParams{})

The MCP protocol supports cursor-based pagination — if a server returns 100+ tools, only the first page is fetched. The fix: loop until toolsResult.NextCursor == "":

var cursor string
for {
    result, err := session.ListTools(ctx, &mcp.ListToolsParams{Cursor: cursor})
    if err != nil { break }
    info.Tools = append(info.Tools, result.Tools...)
    if result.NextCursor == "" { break }
    cursor = result.NextCursor
}

Same pattern for ListResources.

2. Document SessionTimeout in HTTP server

pkg/cli/mcp_server_http.go sets SessionTimeout: 2 * time.Hour with no comment explaining the rationale. A brief note (e.g., "accounts for long-running agent workflows") helps future maintainers.

✨ Feature Opportunities

3. Expose workflow files as MCP Resources

The server currently registers no MCP resources. Workflow .md and compiled .lock.yml files could be exposed as resources (e.g., (redacted) allowing AI agents to read workflow content directly via resources/readwithout needing a custom tool. This is especially useful for agents that want to understand the current workflow state before callingcompileorfix`.

4. Use session.ListRoots in inspector (with fallback)

pkg/cli/mcp_inspect_mcp.go uses extractRootsFromResources — a heuristic that guesses root URIs by parsing resource URI schemes. If the inspected server supports the roots capability, session.ListRoots would return the actual roots. The current heuristic could serve as a fallback.

5. Declare Output Schemas for JSON-returning tools

The mcp.AddTool handler signature returns (*mcp.CallToolResult, any, error) — the second value is a typed struct that declares the output schema. Currently all tools return nil. Tools like status, checks, and audit always emit a known JSON structure; declaring their output schema would:

• Enable MCP clients to validate and introspect tool outputs
• Improve discoverability for AI agents
• Align with the SDK's structured output feature

📐 Best Practice Alignment

6. Cross-origin protection is now automatic — document it

Since v1.4.1, mcp.NewStreamableHTTPHandler automatically verifies Origin and Content-Type headers to protect against CSRF attacks. Since v1.4.0, DNS rebinding protection is automatic for localhost. gh-aw gets both for free — worth a comment in mcp_server_http.go so maintainers know not to add redundant middleware.

7. SDK now handles input validation errors as tool results

In v1.5.0, JSON schema validation errors from mcp.AddTool are returned as CallToolResult with IsError: true instead of JSON-RPC errors. This improves LLM interaction (LLMs can read the error, fix their inputs, and retry). gh-aw's custom validators (e.g., conflicting firewall/no_firewall flags) still correctly return jsonrpc.Error — that's the right choice for logical errors, not schema errors.

---

Recommendations

Priority	Action	Effort
🔴 Medium	Add pagination to ListTools/ListResources in inspector	Small — ~15 lines
🟡 Low	Add output schemas to JSON-returning tools (status, checks, audit)	Medium — requires schema structs
🟡 Low	Expose workflow files as MCP Resources	Medium — new registration code
🟢 Trivial	Document SessionTimeout rationale in HTTP server	Trivial — 1 comment
🟢 Trivial	Add comment about automatic cross-origin/DNS rebinding protection	Trivial — 1 comment

Overall Assessment

gh-aw is a sophisticated and idiomatic user of the MCP Go SDK. The project is on the latest version (v1.5.0), uses the typed mcp.AddTool pattern, properly applies tool annotations, handles errors correctly, and already adopts performance optimizations like DisableStandaloneSSE. The main gaps are the missing tool listing pagination (a real correctness issue for servers with many tools) and the untapped structured output feature.

---

Module summary saved to: scratchpad/mods/modelcontextprotocol-go-sdk.md
References: §24712025716

Note

🔒 Integrity filter blocked 1 item

The following item was blocked because it doesn't meet the GitHub integrity level.

• cli/go-gh@55692c6 get_commit: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".

To allow these resources, lower min-integrity in your GitHub frontmatter:

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

Generated by Go Fan · ● 355.7K · ◷

• expires on Apr 22, 2026, 8:30 AM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Go Fan.

A newer discussion is available at Discussion #27788.