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

[github-actions[bot]]

🐹 Go Fan Report: modelcontextprotocol/go-sdk

The MCP SDK received a major v1.1.0 update on October 30, 2025, with significant new features and critical bug fixes. The repository is extremely active with 20 commits in the past 10 days addressing performance, security, and conformance. gh-aw uses the SDK extensively for its MCP server and gateway implementations, but is missing several important v1.1.0 features.

Module Overview

github.com/modelcontextprotocol/go-sdk is the official Go SDK for the Model Context Protocol (MCP), enabling gh-aw to:

• Expose CLI commands as MCP tools via an MCP server
• Create an MCP gateway to proxy multiple backend MCP servers
• Parse and validate MCP configurations from workflow frontmatter
• Inspect remote MCP servers and enumerate available tools

Current Version: v1.1.0 (stable release, October 30, 2025)
Repository Activity: Very active (20 commits in 10 days, released from v1.0.0 on September 30)

Current Usage in gh-aw

Production Files (4 files)

• pkg/cli/mcp_server.go - Main MCP server wrapping gh-aw CLI commands as tools
• pkg/gateway/gateway.go - MCP gateway for proxying multiple servers
• pkg/parser/mcp.go - Parses MCP server configs from frontmatter
• pkg/cli/mcp_inspect_mcp.go - Inspects remote MCP servers

Test Files (11 files)

Integration and unit tests for MCP functionality

Key Usage Patterns

// Server pattern (pkg/cli/mcp_server.go:104)
server := mcp.NewServer(&mcp.Implementation{
    Name: "gh-aw",
    Version: GetVersion(),
}, nil)  // ⚠️ Passing nil options - missing v1.1.0 features!

// Gateway pattern (pkg/gateway/gateway.go:94)
handler := mcp.NewStreamableHTTPHandler(func(req *http.Request) *mcp.Server {
    return server
}, nil)  // ⚠️ No SessionTimeout, Logger, or EventStore configured!

// Client pattern (scattered across tests)
client := mcp.NewClient(&mcp.Implementation{...}, nil)

Research Findings

Recent v1.1.0 Updates (October 30, 2025)

🆕 Major New Features

1. ServerOptions.Logger - Structured server-side logging (MCP Network Permissions Test Results - Domain Restrictions Analysis #170)

   • Replaces scattered log.Printf calls
   • Enables proper log level control and formatting

2. IOTransport - General-purpose transport ([Custom Engine Test] Test Issue Created by Custom Engine #444)

   • Works with any io.ReadCloser / io.WriteCloser
   • Enables TCP sockets, Unix sockets, custom I/O

3. StreamableHTTPOptions.SessionTimeout - Auto-close idle sessions (Simplify workflow compiler code generation with helper utilities #499)

   • Prevents resource leaks from abandoned connections
   • Critical for production multi-user servers

4. StreamableHTTPOptions.EventStore - Explicit stream resumption control ([Custom Engine Test] Test Issue Created by Custom Engine #587)

   • Default changed: resumption now disabled by default
   • Set explicitly if resumption is needed
   • Prevents unbounded memory growth

5. TokenInfo.UserID - Session hijacking prevention ([Custom Engine Test] Test Pull Request - Custom Engine Safe Output #589, [UPDATED] Update Issue Test - Processed by Claude #695)

   • Binds sessions to users via JWT "sub" claims
   • Prevents token theft attacks

🐛 Critical Bug Fixes (Past 10 Days)

1. HTTP Connection Reuse (Dec 10, Test Issue for Commands #677)

   • Fixed: connections not being reused, causing performance issues
   • Solution: Read full response body to enable pooling
   • Impact: Major performance improvement for gateway usage

2. Stray Logging (Dec 10, Test Issue for Claude Commands #708, Hello from Claude #684)

   • Fixed: log.Printf calls polluting stderr
   • Solution: Thread logger through all subsystems

3. Context Cancellation (Dec 3, #662)

   • Better handling for request cancellation
   • Prevents shutdown deadlocks

📐 Behavior Changes

• Stream resumption disabled by default - Was enabled with in-memory store
• Prime/close events gated on protocol version 2025-11-25 (Add --purge flag to compile command to delete orphaned .lock.yml files #696)

Best Practices from SDK Maintainers

1. ✅ Use ServerOptions.Logger instead of log.Printf
2. ✅ Set SessionTimeout to prevent resource leaks
3. ✅ Disable stream resumption (default) for multi-user servers
4. ✅ Populate TokenInfo.UserID to prevent session hijacking
5. ✅ Handle context cancellation in long-running operations
6. ✅ Read full HTTP response bodies for connection reuse
7. ✅ Gate new features on protocol version

Improvement Opportunities

🏃 Quick Wins

1. Add ServerOptions.Logger for Structured Logging

Files: pkg/cli/mcp_server.go:104, pkg/gateway/gateway.go:85
Effort: One-line change per file
Impact: Consistent structured logging across MCP operations

server := mcp.NewServer(&mcp.Implementation{
    Name: "gh-aw",
    Version: GetVersion(),
}, &mcp.ServerOptions{
    Logger: mcpLog,  // Use existing logger
})

2. Add SessionTimeout to HTTP Handler

Files: pkg/cli/mcp_server.go:83, pkg/gateway/gateway.go:94
Effort: One-line change
Impact: Prevents resource leaks from abandoned sessions

handler := mcp.NewStreamableHTTPHandler(serverFunc, &mcp.StreamableHTTPOptions{
    Logger: mcpLog,
    SessionTimeout: 30 * time.Minute,
})

3. Add Context Timeout Handling

Files: All tool handlers in pkg/cli/mcp_server.go
Effort: Add select statement for long operations
Impact: Better reliability and cancellation support

select {
case <-ctx.Done():
    return nil, nil, ctx.Err()
case result := <-resultChan:
    return result, nil, nil
}

✨ Feature Opportunities

4. Session Hijacking Prevention with UserID

Where: Gateway authentication middleware
Why: v1.1.0 added TokenInfo.UserID for session-to-user binding
Security: Prevents token theft in multi-user gateways

5. HTTP Connection Pooling Configuration

Where: Client creation in pkg/gateway/gateway.go:131
Why: v1.1.0 fixed connection reuse issues
Benefit: Better performance for high-volume usage

6. Use IOTransport for Custom Scenarios

Where: Future enhancements
Use Case: TCP socket or Unix socket communication with MCP servers

7. Leverage RequestExtra.CloseStream

Where: Tool handlers
Why: SEP-1699 support (prime/close events)
Benefit: Graceful stream termination with reconnection hints

📐 Best Practice Alignment

8. Consolidate Client Creation

Where: Test files (11 occurrences)
Current: Repeated mcp.NewClient(&mcp.Implementation{...}, nil)
Better: Extract to pkg/testutil/mcp.go helper

9. Add ClientOptions Configuration

Where: pkg/gateway/gateway.go:131
Current: Passing nil for options
Better: Configure protocol version, retry behavior

opts := &mcp.ClientOptions{
    ProtocolVersion: "2025-11-25",  // Latest features
}
session, err := client.Connect(ctx, transport, opts)

10. Validate Command Availability

Where: pkg/cli/mcp_server.go:94-101 (execCmd)
Current: No validation that gh aw exists
Better: Check at server startup, fail fast

🔧 General Improvements

11. Implement Graceful Shutdown

Where: pkg/cli/mcp_server.go:115
Current: No shutdown handling
Better: Listen for signals, call httpServer.Shutdown(ctx)

12. Add Conformance Testing

Where: CI pipeline
Why: SDK provides conformance suite (Dec 8 commit)
How: Use scripts/run_conformance_tests.sh from SDK

13. Add Metrics for MCP Operations

Where: Tool handlers and gateway
Why: Monitor usage, latency, errors
How: Wrap handlers with metrics middleware

14. Document Protocol Version Compatibility

Where: README or inline comments
Why: Features like prime/close require protocol 2025-11-25+

Recommendations

Priority 1 (Immediate - Zero Risk)

1. ✅ Add ServerOptions.Logger - One-line change, immediate structured logging
2. ✅ Add SessionTimeout - Prevents resource leaks in production
3. ✅ Update golang.org/x/term to v0.38.0 - Already in go.mod, align cache

Priority 2 (Next Sprint)

4. Add context timeout handling - Improves reliability
5. Consolidate client creation - Reduces test duplication
6. Validate command availability - Better UX

Priority 3 (Future Enhancements)

7. Session hijacking prevention - Security hardening
8. HTTP connection pooling - Performance optimization
9. Conformance testing - Continuous compliance

SDK Stability & Maturity

• ✅ v1.0.0 stability reached September 30, 2025
• ✅ Backward compatibility guarantee - no breaking changes
• ✅ 60/61 reported bugs fixed
• ✅ Conformance test suite available
• ✅ Security policy and nightly vulnerability scanning
• ✅ Very active maintenance - 20 commits in 10 days

Next Steps

1. Quick wins: Apply ServerOptions.Logger and SessionTimeout (1-line changes)
2. Testing: Run SDK conformance tests against gh-aw's MCP server
3. Security review: Evaluate need for TokenInfo.UserID in gateway
4. Performance testing: Measure impact of v1.1.0 connection reuse fixes

---

Module summary saved to: specs/mods/go-sdk.md

References:

• https://github.com/modelcontextprotocol/go-sdk/releases/tag/v1.1.0
• https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk
• (redacted)

AI generated by Go Fan

[github-actions[bot]]

⚓ Avast! This discussion be marked as outdated by Go Fan.
🗺️ A newer treasure map awaits ye at Discussion #6222.
Fair winds, matey! 🏴‍☠️