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

# 🐹 Go Fan Report: Model Context Protocol Go SDK

## Module Overview

The **Model Context Protocol (MCP) Go SDK** is the official Go implementation for building MCP servers and clients. Maintained in collaboration with Google, it provides comprehensive support for creating AI agent tool interfaces with multiple transport options (stdio, HTTP/SSE, WebSocket).

- **Module**: `github.com/modelcontextprotocol/go-sdk`
- **Current Version**: v1.3.0 (latest, released 2026-02-09)
- **Repository**: https://github.com/modelcontextprotocol/go-sdk
- **Activity**: ⭐ 3823 stars | Very active (updated 2026-02-11)

## Current Usage in gh-aw

### Implementation Scale
- **15+ files** actively using the SDK
- **Primary server**: 1023-line MCP server exposing 6+ tools
- **Client usage**: Server inspection and management
- **Transport modes**: Both stdio and HTTP/SSE supported

### Key Integration Points

**Server Implementation** (`pkg/cli/mcp_server.go`):
```go
server := mcp.NewServer(&mcp.Implementation{
    Name: "gh-aw",
    Version: GetVersion(),
}, &mcp.ServerOptions{
    Capabilities: &mcp.ServerCapabilities{
        Tools: &mcp.ToolCapabilities{
            ListChanged: false,
        },
    },
    Logger: logger.NewSlogLoggerWithHandler(mcpLog),
})
```

**Tools Exposed**:
- `status` - Workflow status monitoring
- `compile` - Workflow compilation with security scanning
- `fix` - Automatic codemod application
- `inspect` - Workflow/schema inspection
- `mcp-server-add` - MCP server configuration
- `mcp-server-operations` - Server management

**Client Implementation** (`pkg/cli/mcp_inspect_mcp.go`):
- Stdio transport for command-based servers
- HTTP/SSE transport with custom header support
- Context-based timeout management (30s connect, 10s operations)

<details>
<summary><b>View Transport Details</b></summary>

### Stdio Transport
```go
client := mcp.NewClient(&mcp.Implementation{
    Name: "gh-aw-inspector",
    Version: "1.0.0"
}, nil)
transport := &mcp.CommandTransport{Command: cmd}
session, err := client.Connect(ctx, transport, nil)
```

### HTTP/SSE Transport
```go
transport := &mcp.StreamableClientTransport{
    Endpoint: config.URL,
}
// Custom headers via headerRoundTripper
session, err := client.Connect(ctx, transport, nil)
```

</details>

## Research Findings

### Recent SDK Updates (v1.3.0 - Feb 2026)

The latest release brings significant performance and reliability improvements:

#### 🚀 Performance Enhancements
- **Schema Caching** (PR #685): Eliminates repeated reflection overhead - major performance win for stateless deployments
- **Error Introspection** (PR #753): `GetError`/`SetError` now exported for better debugging

#### 🔌 Transport Improvements
- **Configurable Message Sizes** (PR #734): HTTP transport now handles messages >1MB
- **StreamableClientTransport** (PR #729): Added `DisableListening` option
- **SSE Stability**: Multiple bugfixes for Content-Type checking, HTTP error reporting, and race conditions

#### 📝 Logger Modernization
- **Deprecated old logger**: Now use `ClientOptions.Logger` (PR #738, #744)
- More flexible configuration options

#### 🔒 Security & Quality
- **Localhost binding**: Auth middleware now defaults to localhost (2026-02-11)
- **Go 1.25 synctest**: Deterministic timing tests
- **JSON fix**: ElicitationCapabilities field names corrected
- **Error export**: `ErrSessionMissing` now accessible

### Best Practices from Upstream

1. **Version Support Matrix**: SDK tracks MCP spec version compatibility
2. **Conformance Testing**: New test suite for spec compliance
3. **Structured Concurrency**: Proper context cancellation patterns
4. **Schema-Driven**: `jsonschema` tags for automatic schema generation
5. **Session Lifecycle**: Always `defer session.Close()`

## Improvement Opportunities

### 🏃 Quick Wins

#### 1. Add Logger to Client Connections
**Current State**: Both client instantiations pass `nil` for options
```go
// pkg/cli/mcp_inspect_mcp.go:162, 250
client := mcp.NewClient(&mcp.Implementation{...}, nil)
```

**Recommended**:
```go
client := mcp.NewClient(&mcp.Implementation{...}, &mcp.ClientOptions{
    Logger: logger.NewSlogLoggerWithHandler(mcpInspectServerLog),
})
```

**Impact**: Better debugging and observability when inspecting MCP servers  
**SDK Feature**: v1.3.0 modernized logger configuration

#### 2. Verify Schema Caching is Active
**Current**: May be generating schemas repeatedly for the same types  
**SDK Feature**: v1.3.0 adds automatic schema caching (PR #685)  
**Action**: Verify the optimization is in effect (should be automatic)  
**Impact**: Performance improvement, especially with multiple tool calls

#### 3. Use Exported Error Sentinels
**SDK Feature**: v1.3.0 now exports `ErrSessionMissing`  
**Benefit**: More reliable error checking vs string comparison  
**Location**: Error handling in `mcp_inspect_mcp.go`

### ✨ Feature Opportunities

#### 4. Implement Icon Themes
**Current**: Tools use simple emoji icons  
**Enhancement**: Use `mcp.IconTheme` constants for light/dark mode support  
**Files**: All tool definitions in `pkg/cli/mcp_server.go`  
**SDK Feature**: SEP-973 (v1.2.0+)

#### 5. Add Tool Metadata
**Enhancement**: Enrich tool definitions with metadata for better discovery  
**Benefit**: Improved tool discoverability in MCP clients  
**SDK Feature**: SEP-973 metadata support

#### 6. Implement Resources API
**Opportunity**: Expose workflow files, schemas, and configs as MCP resources  
**Use Case**: Allow clients to read `.github/workflows/*.yml` files  
**Benefit**: Clients can inspect and watch project resources  
**Impact**: Major feature addition - enables resource-based workflows

#### 7. Add Prompts API
**Opportunity**: Define standardized prompt templates for common operations  
**Use Cases**: "compile workflow", "inspect workflow" prompt templates  
**Benefit**: Consistent workflow invocation across different clients

### 📐 Best Practice Alignment

#### 8. Configure HTTP Message Sizes
**Current**: Default size limits  
**Recommendation**: Configure larger limits for compile tool output  
**Location**: HTTP server setup in `pkg/cli/mcp_server.go`  
**SDK Feature**: v1.3.0 adds configurable message sizes  
**Impact**: Handle large compilation outputs without truncation

#### 9. Improve Error Code Granularity
**Current**: Heavy reliance on `jsonrpc.CodeInternalError` (20+ occurrences)  
**Better Approach**:
- `CodeMethodNotFound` for unsupported operations
- `CodeInvalidRequest` for malformed requests  
- `CodeRequestCancelled` for context cancellation

**Benefit**: Clients can handle errors more intelligently  
**SDK Feature**: Common error codes available as sentinels

#### 10. Leverage Session Reuse
**Current**: Connect → query → close pattern per inspection  
**SDK Enhancement**: v1.2.0 allows connection reuse in more cases (PR #709)  
**Location**: `pkg/cli/mcp_inspect_mcp.go`  
**Benefit**: Reduced connection overhead for multiple operations

#### 11. Enhanced Context Cancellation
**Current**: Good timeout usage throughout  
**SDK**: v1.2.0 improved streamable context cancellation (PR #677)  
**Benefit**: More graceful handling of cancelled operations

### 🔧 General Improvements

#### 12. Add Conformance Testing
**Current**: Comprehensive unit tests  
**Enhancement**: Add tests using `modelcontextprotocol/conformance`  
**Benefit**: Ensure MCP spec compliance  
**SDK**: v1.2.0 adds conformance test support

#### 13. Stay Current with SDK Releases
**Current**: Using latest v1.3.0 ✅  
**Strategy**: Monitor SDK releases (very active development)  
**Benefit**: Access to bug fixes, performance improvements, new features  
**Note**: SDK has formal dependency update policy in CONTRIBUTING.md

#### 14. Go Version Alignment
**Current**: `go 1.25.0` ✅  
**SDK**: Explicitly supports Go 1.25+ (uses synctest)  
**Status**: Well-aligned - can leverage latest Go features

## Recommendations

### 🎯 Priority 1: Implement Soon
1. **Add logger to client connections** - Immediate debugging value
2. **Verify schema caching** - Confirm performance optimization is active
3. **Use exported error sentinels** - More reliable error handling

### 🎯 Priority 2: Next Iteration
4. **Implement resources API** - Major feature: expose workflow files
5. **Configure HTTP message sizes** - Handle large compilation outputs
6. **Improve error code granularity** - Better client error handling

### 🎯 Priority 3: Future Enhancements
7. **Add icon themes** - Visual consistency across clients
8. **Implement prompts API** - Standardized workflow invocations
9. **Add conformance tests** - Ensure spec compliance

## Next Steps

1. **Update ClientOptions**: Add logger to both client instantiations in `mcp_inspect_mcp.go:162, 250`
2. **Review error handling**: Identify string-based error checks that could use `ErrSessionMissing`
3. **Design resources**: Determine which files/configs should be exposed as MCP resources
4. **Monitor SDK**: Subscribe to release notifications at https://github.com/modelcontextprotocol/go-sdk/releases

## Module Assessment

### Strengths ✅
- **Proper context management**: Timeouts on all operations
- **Error handling**: Consistent use of `jsonrpc.Error`
- **Dual transport**: Both stdio and HTTP/SSE supported
- **Custom headers**: headerRoundTripper for HTTP flexibility
- **Comprehensive testing**: 15+ test files with good coverage
- **Schema-driven**: Effective use of jsonschema tags
- **Up-to-date**: Using latest SDK version (v1.3.0)

### Well-Utilized ⭐
gh-aw makes excellent use of the MCP SDK's core capabilities. The implementation is solid, idiomatic, and well-structured. The identified improvements are primarily about leveraging new v1.3.0 features and expanding functionality (resources, prompts) rather than fixing issues.

---

**References:**
- Repository: https://github.com/modelcontextprotocol/go-sdk
- Documentation: (modelcontextprotocol.io/redacted)
- Module summary: `scratchpad/mods/modelcontextprotocol-go-sdk.md`
- Last reviewed: 2026-02-12

*Generated by Go Fan 🐹*
*Round-robin selection: Chose most recently updated unreviewed module (pushed 2026-02-11)*

---

> **Note:** This was intended to be a discussion, but discussions could not be created due to permissions issues. This issue was created as a fallback.







> AI generated by [Go Fan](https://github.com/github/gh-aw/actions/runs/21937263674)
> - [x] expires  on Feb 19, 2026, 7:28 AM UTC

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

Description

🐹 Go Fan Report: Model Context Protocol Go SDK

Module Overview

Current Usage in gh-aw

Implementation Scale

Key Integration Points

Stdio Transport

HTTP/SSE Transport

Research Findings

Recent SDK Updates (v1.3.0 - Feb 2026)

🚀 Performance Enhancements

🔌 Transport Improvements

📝 Logger Modernization

🔒 Security & Quality

Best Practices from Upstream

Improvement Opportunities

🏃 Quick Wins

1. Add Logger to Client Connections

2. Verify Schema Caching is Active

3. Use Exported Error Sentinels

✨ Feature Opportunities

4. Implement Icon Themes

5. Add Tool Metadata

6. Implement Resources API

7. Add Prompts API

📐 Best Practice Alignment

8. Configure HTTP Message Sizes

9. Improve Error Code Granularity

10. Leverage Session Reuse

11. Enhanced Context Cancellation

🔧 General Improvements

12. Add Conformance Testing

13. Stay Current with SDK Releases

14. Go Version Alignment

Recommendations

🎯 Priority 1: Implement Soon

🎯 Priority 2: Next Iteration

🎯 Priority 3: Future Enhancements

Next Steps

Module Assessment

Strengths ✅

Well-Utilized ⭐

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions