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

[github-actions]

🐹 Go Fan Report: modelcontextprotocol/go-sdk

Module Overview

The modelcontextprotocol/go-sdk is the official Go SDK for Model Context Protocol servers and clients, maintained in collaboration with Google. This SDK provides comprehensive support for building MCP servers and clients in Go, including HTTP/SSE transport, stdio transport, tool/resource/prompt registration, and session management.

Repository: https://github.com/modelcontextprotocol/go-sdk
Version Used: v1.3.0 ✅ (Latest)
Last Updated: 2026-02-18 (Today!)
Stars: 3,875 ⭐

Current Usage in gh-aw-mcpg

Files & Import Statistics

• Files: 20 files (5 production + 15 test files)
• Import Count: 20 direct imports
• Key APIs Used:
  • Server APIs: NewServer(), AddTool(), NewStreamableHTTPHandler(), StreamableHTTPOptions
  • Client APIs: NewClient(), Connect(), ListTools(), CallTool()
  • Transport APIs: NewInMemoryTransports(), StreamableHTTP with session support

Production Files

1. internal/server/transport.go - StreamableHTTP handler creation
2. internal/server/unified.go - Unified mode server implementation
3. internal/server/routed.go - Routed mode server implementation
4. internal/mcp/connection.go - Client connections to backend MCP servers
5. internal/testutil/mcptest/ - Test infrastructure (3 files)

Current Patterns

Server Creation:

sdk.NewServer(&sdk.Implementation{
    Name:    "awmg-unified",
    Version: "1.0.0",
}, nil)  // ⚠️ No server options used

Client Creation:

sdk.NewClient(&sdk.Implementation{
    Name:    "awmg",
    Version: version.Get(),
}, &sdk.ClientOptions{})  // ⚠️ Empty options

StreamableHTTP (Good!):

&sdk.StreamableHTTPOptions{
    Stateless:      false,
    Logger:         logger.NewSlogLoggerWithHandler(logTransport),
    SessionTimeout: 30 * time.Minute,
}

Research Findings

Recent Updates (v1.3.0 - Released 2026-02-09)

The project is using the latest version of the SDK! v1.3.0 includes significant improvements:

1. ✨ Schema Caching - Dramatically improves performance in stateless server scenarios
2. 🔧 Logger in ClientOptions - Logging moved from deprecated location to ClientOptions
3. 🛡️ GetError/SetError Export - Better structured error handling
4. 🐛 Case-Insensitive HTTP Headers - Fixed SSE Content-Type checking bug
5. ⚡ Race Condition Fix - Fixed logging race condition
6. 📋 HTTP 405 Compliance - Added Allow header per RFC 9110

Best Practices from SDK Maintainers

1. Logger Integration: Pass logger through ClientOptions and ServerOptions for complete visibility
2. Error Handling: Use SDK's GetError/SetError methods for structured error context
3. Session Management: Leverage StreamableHTTP with timeouts (✅ already doing this!)
4. Schema Caching: Automatic in v1.3.0, provides significant performance gains

SDK Features We're NOT Using

1. Resources API - Only test usage, no production resources exposed
2. Prompts API - Zero usage (could provide helpful templates)
3. Completion API - Zero usage
4. Sampling API - Zero usage (LLM integration)
5. Extensions (SEP-2133) - New capability for custom protocol extensions
6. Advanced Logging - Logger only in transport, not in client/server options
7. Structured Error Types - Custom HTTP errors instead of SDK types

Improvement Opportunities

🏃 Quick Wins

1. Add Logger to ClientOptions ⭐ HIGH PRIORITY

• Current: &sdk.ClientOptions{} (empty)
• Fix: Pass project logger to SDK
• Benefit: Unified logging across gateway and SDK operations
• Effort: 1-2 hours
• Location: internal/mcp/connection.go:165
• Code:

  &sdk.ClientOptions{
      Logger: logger.NewSlogLoggerWithHandler(logClient),
  }

2. Add Logger to ServerOptions ⭐ HIGH PRIORITY

• Current: sdk.NewServer(..., nil) (no options)
• Fix: Pass logger via server options
• Benefit: Better visibility into SDK server operations
• Effort: 1-2 hours
• Locations: internal/server/unified.go:136, internal/server/routed.go:187

3. Validate Schema Caching Performance

• Current: Automatic in v1.3.0 (good!)
• Improvement: Add metrics to quantify performance gains
• Benefit: Document actual performance improvements
• Effort: 2-3 hours

✨ Feature Opportunities

1. Implement Resources API (Medium Complexity)

Opportunity: Expose gateway state as MCP resources

Potential Resources:

• /config - Current gateway configuration
• /health - Gateway health status
• /metrics - Performance metrics
• /backends - Backend server status
• /sessions - Active session information

Benefit: Clients can query gateway state using standard MCP protocol instead of custom APIs

Effort: 4-6 hours for basic implementation

Example:

server.AddResource(&sdk.Resource{
    URI:  "config://gateway",
    Name: "Gateway Configuration",
    Description: "Current gateway configuration",
    MimeType: "application/json",
}, configResourceHandler)

2. Implement Prompts API (Medium Complexity)

Opportunity: Provide prompt templates for common operations

Potential Prompts:

• configure-backend - Template for adding new backend server
• debug-connection - Template for debugging connection issues
• check-health - Template for health checks

Benefit: Better developer experience for gateway configuration and debugging

Effort: 4-6 hours

3. Add Extensions Support - SEP-2133 (Medium Complexity)

Opportunity: Implement gateway-specific protocol extensions

Potential Extensions:

• awmg.routing - Custom routing metadata
• awmg.session - Session management extensions
• awmg.pooling - Connection pool information

Benefit: Extend MCP protocol with gateway-specific features

Effort: 6-8 hours

📐 Best Practice Alignment

1. Logger Integration Gap

• Current: Logger only in StreamableHTTPOptions
• Best Practice: Logger in all client/server options
• Impact: Missing SDK internal operations in logs
• Fix: Priority 1 quick wins above

2. Error Handling Modernization

• Current: Custom HTTP error handling
• Best Practice: Use SDK's GetError/SetError (newly exported in v1.3.0)
• Benefit: Structured error context, better debugging
• Effort: 6-8 hours to migrate

3. Session Management ✅ EXCELLENT

• Status: Already well-aligned!
• Using: StreamableHTTP with 30-minute timeout
• Using: Stateful session support
• No changes needed

🔧 General Improvements

1. Consolidate Client Factory

Create a standard factory function for client creation:

func newMCPClientWithLogger(logger Logger) *sdk.Client {
    return sdk.NewClient(&sdk.Implementation{
        Name:    "awmg",
        Version: version.Get(),
    }, &sdk.ClientOptions{
        Logger: logger,
    })
}

Benefit: DRY principle, consistent client configuration

2. Add Request/Response Logging

Use SDK logger to log MCP protocol messages for better debugging

Benefit: Easier troubleshooting of backend communication issues

3. Metrics Collection

Track SDK operations: connects, tool calls, errors

Benefit: Production monitoring and alerting

4. Connection Pooling Validation

Add logging/metrics to verify SDK connection reuse in SessionConnectionPool

Benefit: Validate session persistence works as expected

Recommendations

🎯 Priority 1: Logger Integration (THIS WEEK)

Effort: 2-4 hours total
Impact: High visibility for troubleshooting

1. Add logger to ClientOptions in internal/mcp/connection.go
2. Add logger to server options in unified/routed modes
3. Create standard factory function for client creation with logging

Expected Outcome: Complete visibility into SDK operations with minimal code changes

🎯 Priority 2: Schema Caching Validation (THIS WEEK)

Effort: 2-3 hours
Impact: Quantify v1.3.0 upgrade benefits

1. Add metrics to track schema cache usage
2. Document performance improvements
3. Share findings with team

Expected Outcome: Data-driven validation of v1.3.0 performance gains

🎯 Priority 3: Resources API (NEXT SPRINT)

Effort: 4-6 hours
Impact: Better observability for clients

1. Start with simple resources: /config, /health, /backends
2. Use existing logger data for resource content
3. Register resources in server creation

Expected Outcome: Clients can query gateway state using standard MCP protocol

🎯 Priority 4: Error Handling Migration (FUTURE)

Effort: 6-8 hours
Impact: Better error context

1. Migrate to SDK error types
2. Use GetError/SetError for structured errors
3. Update error logging

Expected Outcome: Standardized, context-rich error handling

Next Steps

Immediate (This Week)

• Add logger to ClientOptions and ServerOptions
• Create client factory function with logging
• Add schema cache metrics

Short-term (Next 2 Weeks)

• Implement basic resources API (/config, /health, /backends)
• Document SDK usage patterns
• Add metrics for SDK operations

Medium-term (Next Month)

• Evaluate prompts API for developer experience
• Consider extensions for gateway-specific features
• Migrate to SDK error types

Long-term (Future)

• Explore sampling API for AI integration
• Consider completion API if relevant
• Stay current with SDK releases

Summary

The project is using the latest version of the go-sdk (v1.3.0) and has solid fundamentals in place, especially with session management. However, we're leaving significant observability and feature opportunities on the table:

✅ What's Working Well:

• Up-to-date with latest SDK release
• Excellent session management with StreamableHTTP
• Proper stateful connections with timeouts
• Good test infrastructure

⚠️ Areas for Improvement:

• Logger integration (empty options = no visibility)
• Unused SDK features (resources, prompts, extensions)
• Custom error handling instead of SDK types
• Missing metrics for SDK operations

💡 Quick Wins Available:
The logger integration changes are low-effort, high-impact improvements that will significantly improve debugging capabilities. These should be prioritized this week.

---

Generated by Go Fan 🐹
Module summary saved to: docs/GO_SDK_MODULE_REVIEW.md
Next review cycle will select a different module

Generated by Go Fan

• expires on Feb 25, 2026, 7:33 AM UTC

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

This Go module review identifies several concrete improvements to our SDK integration, including adding logger to ClientOptions, using SDK error types, and leveraging new v1.3.0 features. Great opportunities for code quality improvements!

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster