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

[github-actions[bot]]

🐹 Go Fan Report: MCP Go SDK

The Model Context Protocol Go SDK is gh-aw's most critical dependency, and excellent news - we're using the latest version (v1.1.0) which was updated yesterday with significant improvements! This official SDK, maintained in collaboration with Google, is the foundation of gh-aw's entire MCP integration architecture.

Module Overview

The MCP Go SDK provides the core APIs for building MCP servers and clients in Go. It's an official, actively maintained SDK with:

• 3,383 stars ⭐
• Daily commits and active development
• Backward compatibility guarantee (v1.0.0+)
• Maintained by the Model Context Protocol organization with Google

Current Usage in gh-aw

gh-aw makes extensive use of the MCP SDK across multiple components:

• 15 files import and use the SDK
• 3 major integration points:
  1. MCP Server (pkg/cli/mcp_server.go) - Exposes gh-aw CLI as MCP tools
  2. MCP Gateway (pkg/gateway/gateway.go) - Multiplexes multiple MCP servers
  3. MCP Inspection (pkg/cli/mcp_inspect_mcp.go) - Inspects external MCP servers

Key APIs Used

• Server creation: NewServer, AddTool, NewStreamableHTTPHandler
• Client operations: NewClient, Connect, CallTool, ListTools
• Transports: StdioTransport, CommandTransport, StreamableClientTransport

Architecture Pattern

gh-aw uses a clever subprocess isolation pattern where the MCP server spawns CLI subprocesses for each tool invocation, ensuring GitHub tokens and secrets remain isolated from the MCP server process.

Research Findings

Recent Updates (v1.1.0 - Released Oct 30, 2025)

The SDK just received major updates yesterday (Dec 12, 2025) including:

1. New Capabilities API (Hello from Claude #713 - merged yesterday!)

   • ServerOptions.Capabilities and ClientOptions.Capabilities
   • Control default capabilities and notification behavior
   • Suppress listChanged notifications with ListChanged: false

2. Forward-Compatible API ([claude-test] Multi-commit test from Claude #718)

   • CloseSSEStream now uses args struct for future extensibility

3. Performance & Reliability

   • Debounced server change notifications ([claude-test] Hello from Claude #717)
   • Fixed client root capabilities ([UPDATED] Update Issue Test - Processed by Claude #698)
   • HTTP connection reuse improvements (Add MCP Server for Safe Outputs with TypeScript Compilation, Go Embedding, NPM Dependency Management, and Organized Project Structure #710)
   • Better stream state management

4. Security

   • URL scheme validation in OAuth to prevent XSS ([Custom Engine Test] Test Issue Created by Custom Engine #526)

5. Operational Features

   • ServerOptions.Logger for server-side logging
   • StreamableHTTPOptions.Logger for HTTP transport logging
   • StreamableHTTPOptions.SessionTimeout for idle session cleanup
   • StreamableHTTPOptions.EventStore for stream resumption control
   • New IOTransport for flexible I/O scenarios

Breaking Changes

• Stream resumption now disabled by default (was a bug fix - previous default was unintended)

Best Practices from Maintainers

• Enable logging for production debugging
• Set session timeouts to prevent resource leaks
• Use the new Capabilities API to control behavior
• Disable stream resumption unless needed

Improvement Opportunities

✨ Feature Opportunities

🏃 Quick Win #1: Adopt New Capabilities API

Priority: HIGH
Files: pkg/cli/mcp_server.go:105, pkg/gateway/gateway.go:85

Current:

server := mcp.NewServer(&mcp.Implementation{
    Name:    "gh-aw",
    Version: GetVersion(),
}, nil)  // ← nil options

Improved:

server := mcp.NewServer(&mcp.Implementation{
    Name:    "gh-aw",
    Version: GetVersion(),
}, &mcp.ServerOptions{
    Capabilities: &mcp.ServerCapabilities{
        ListChanged: false,  // Tools are static, no notifications needed
    },
    Logger: mcpLogger,  // Enable structured logging
})

Benefits:

• Disable unnecessary listChanged notifications (tools are static)
• Better observability with structured logging
• Aligns with latest SDK patterns

---

🏃 Quick Win #2: Add Server-Side Logging

Priority: MEDIUM
Files: pkg/cli/mcp_server.go, pkg/gateway/gateway.go

Implementation:

// Create logger adapter for MCP SDK
type mcpLogger struct {
    log *logger.Logger
}

func (l *mcpLogger) Info(msg string, keysAndValues ...any) {
    l.log.Printf("[INFO] %s %v", msg, keysAndValues)
}
// ... implement Debug, Warn, Error methods

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

Benefits:

• Track MCP tool invocations and errors
• Better debugging of MCP integration issues
• Integrates with gh-aw's existing logging infrastructure

---

🏃 Quick Win #3: Configure Session Timeouts

Priority: MEDIUM
Files: pkg/cli/mcp_server.go:666, pkg/gateway/gateway.go:94

Current:

handler := mcp.NewStreamableHTTPHandler(func(req *http.Request) *mcp.Server {
    return server
}, nil)  // ← nil options

Improved:

handler := mcp.NewStreamableHTTPHandler(func(req *http.Request) *mcp.Server {
    return server
}, &mcp.StreamableHTTPOptions{
    SessionTimeout: 30 * time.Minute,  // Clean up abandoned sessions
    Logger:         mcpLogger,          // HTTP transport logging
})

Benefits:

• Prevents resource leaks from abandoned HTTP sessions
• Essential for production MCP gateways
• Better resource management for long-running services

---

📐 Best Practice Alignment

✅ Stream Resumption (Already Aligned!)

gh-aw correctly uses nil for StreamableHTTPOptions, which now properly disables stream resumption by default in v1.1.0. No action needed!

⚠️ Context Cancellation (LOW PRIORITY)

Tool handlers could benefit from checking ctx.Done() before long-running operations to properly handle client disconnections.

---

🔧 General Improvements

1. Test Latest API Changes

Priority: HIGH

Action items:

• Verify compatibility with yesterday's Capabilities API
• Test that existing nil ServerOptions still works
• Validate HTTP connection reuse improvements

2. Monitor SDK Evolution

• Watch for v2 plans (maintainers mentioned potential future v2)
• SDK committed to no breaking changes in v1.x
• Stay current with security fixes

---

Recommendations

Immediate Actions (This Sprint)

1. Add Capabilities configuration to MCP servers with logging enabled
2. Test compatibility with yesterday's SDK changes
3. Configure session timeouts for HTTP gateways

Near-Term Actions (Next Sprint)

1. Implement server-side logging throughout MCP integration
2. Add context cancellation checks to tool handlers
3. Review and test connection reuse improvements

Long-Term Actions

1. Monitor SDK for v2 migration announcements
2. Consider adopting IOTransport for custom scenarios
3. Evaluate experimental OAuth support (if needed)

---

Testing Notes

Key areas to test:

• ✅ Verify backward compatibility with v1.1.0
• ✅ Test Capabilities API with nil options (default behavior)
• ✅ Validate HTTP concurrent connections (recent perf fix)
• ✅ Test session timeout behavior under load

---

Security Considerations

• ✅ SDK fixed XSS in OAuth URLs ([Custom Engine Test] Test Issue Created by Custom Engine #526)
• ✅ Subprocess isolation prevents token leakage
• ⚠️ Consider adding tool execution timeouts for DoS prevention

---

Next Steps

The gh-aw team should:

1. Review this analysis and prioritize improvements
2. Test compatibility with yesterday's Capabilities API changes
3. Implement Quick Wins rejig docs #1-3 in upcoming development cycles
4. Continue monitoring SDK releases for relevant updates

---

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

Module Version: v1.1.0 (Latest - Up to date!)
Last SDK Update: December 12, 2025 (yesterday!)
Review Date: December 12, 2025

AI generated by Go Fan

[pelikhan]

/plan

[github-actions[bot]]

🎉 Yo ho ho! Plan Command found the treasure and completed successfully! ⚓💰

#6255

[github-actions[bot]]

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