go-zero/mcp/MIGRATION.md

Migration to Official MCP SDK

This document describes the migration from the custom MCP implementation to the official go-sdk.

Changes

Dependencies

Added the official MCP SDK:

go get github.com/modelcontextprotocol/go-sdk@v1.2.0

Type System

All types are now re-exported from the official SDK:

• Tool → sdkmcp.Tool
• CallToolRequest → sdkmcp.CallToolRequest
• CallToolResult → sdkmcp.CallToolResult
• Content types (TextContent, ImageContent, etc.)
• Prompt, Resource, Server, ServerSession

Server Interface

The McpServer interface has been simplified:

type McpServer interface {
    Start()
    Stop()
    Server() *sdkmcp.Server  // Returns underlying SDK server
}

Important: The AddTool, AddPrompt, and AddResource methods have been removed. Use the SDK directly:

// Old (no longer supported)
server.AddTool(tool, handler)

// New (use SDK directly)
sdkmcp.AddTool(server.Server(), tool, handler)

Configuration

Updated configuration structure:

• Removed: ProtocolVersion, BaseUrl (SDK manages these)
• Added: UseStreamable (choose between SSE and Streamable HTTP transport)

mcp:
  name: my-server
  version: 1.0.0
  useStreamable: false  # false = SSE (2024-11-05), true = Streamable HTTP (2025-03-26)
  sseEndpoint: /sse
  messageEndpoint: /message
  sseTimeout: 24h
  messageTimeout: 30s
  cors:
    - http://localhost:3000

Tool Registration

The SDK uses Go generics for type-safe tool registration:

import sdkmcp "github.com/modelcontextprotocol/go-sdk/mcp"

type MyArgs struct {
    Value string `json:"value" jsonschema:"description=Input value"`
}

tool := &mcp.Tool{
    Name:        "my_tool",
    Description: "Description",
}

handler := func(ctx context.Context, req *mcp.CallToolRequest, args MyArgs) (*mcp.CallToolResult, any, error) {
    return &mcp.CallToolResult{
        Content: []mcp.Content{
            &mcp.TextContent{Text: "Result"},
        },
    }, nil, nil
}

// Register with explicit type parameters
sdkmcp.AddTool(server.Server(), tool, handler)

The SDK automatically generates JSON schemas from struct tags.

Transport Support

Two transports are supported:

1. SSE (Server-Sent Events): 2024-11-05 MCP spec

   • Default (UseStreamable: false)
   • Endpoint: /sse (configurable)
   • Bidirectional: client sends messages to /message

2. Streamable HTTP: 2025-03-26 MCP spec

   • Opt-in (UseStreamable: true)
   • Endpoint: /sse (configurable)
   • Newer protocol with improved streaming

Example Migration

Before:

server := mcp.NewMcpServer(c)

tool := &mcp.Tool{Name: "greet", Description: "Greet"}
handler := func(ctx context.Context, req *mcp.CallToolRequest, args GreetArgs) (*mcp.CallToolResult, any, error) {
    return &mcp.CallToolResult{
        Content: []mcp.Content{&mcp.TextContent{Text: "Hello"}},
    }, nil, nil
}

if err := server.AddTool(tool, handler); err != nil {
    log.Fatal(err)
}

After:

import sdkmcp "github.com/modelcontextprotocol/go-sdk/mcp"

server := mcp.NewMcpServer(c)

tool := &mcp.Tool{Name: "greet", Description: "Greet"}
handler := func(ctx context.Context, req *mcp.CallToolRequest, args GreetArgs) (*mcp.CallToolResult, any, error) {
    return &mcp.CallToolResult{
        Content: []mcp.Content{&mcp.TextContent{Text: "Hello"}},
    }, nil, nil
}

// Use SDK directly - no error return
sdkmcp.AddTool(server.Server(), tool, handler)

Benefits

1. Official SDK: Uses the official Model Context Protocol SDK
2. Type Safety: Go generics provide compile-time type checking
3. Auto Schema: JSON schemas generated automatically from struct tags
4. Dual Transport: Supports both SSE and Streamable HTTP transports
5. Maintained: SDK is actively maintained by the MCP team

Breaking Changes

1. server.AddTool() removed → use sdkmcp.AddTool(server.Server(), ...)
2. server.AddPrompt() removed (SDK v1.2.0 limitation)
3. server.AddResource() removed (SDK v1.2.0 limitation)
4. Config fields ProtocolVersion and BaseUrl removed
5. All types now come from SDK (re-exported for convenience)

Migration Checklist

• Update imports: add sdkmcp "github.com/modelcontextprotocol/go-sdk/mcp"
• Replace server.AddTool() with sdkmcp.AddTool(server.Server(), ...)
• Remove error handling for tool registration (SDK doesn't return errors)
• Update config: remove ProtocolVersion and BaseUrl, add UseStreamable
• Test with both SSE and Streamable transports
• Update documentation/examples