MCP Tool Serialization

The Model Context Protocol (MCP) allows servers to expose tools that can be used by AI models. The Go-AI SDK provides methods to retrieve tool definitions in a format that can be stored, transmitted, or cached.

GetSerializableTools()

The GetSerializableTools() method returns tool definitions from an MCP server in a JSON-serializable format with full pagination support.

Method Signature

func (c *MCPClient) GetSerializableTools(ctx context.Context) (*ListToolsResult, error)

Return Type

type ListToolsResult struct {
    Tools      []MCPTool `json:"tools"`
    NextCursor string    `json:"nextCursor,omitempty"`
}

type MCPTool struct {
    Name         string                 `json:"name"`
    Title        string                 `json:"title,omitempty"`
    Description  string                 `json:"description,omitempty"`
    InputSchema  map[string]interface{} `json:"inputSchema"`
    OutputSchema map[string]interface{} `json:"outputSchema,omitempty"`
    Annotations  map[string]interface{} `json:"annotations,omitempty"`
    Meta         map[string]interface{} `json:"_meta,omitempty"`
}

MCPTool preserves the current MCP tool JSON shape, including title, outputSchema, annotations, and _meta. MCP Apps metadata is stored in _meta.ui or the legacy flat _meta["ui/resourceUri"] field and can be normalized with mcp.GetMCPAppToolMeta.

Basic Usage

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"

    "github.com/digitallysavvy/go-ai/pkg/mcp"
)

func main() {
    // Create MCP client
    transport := mcp.NewStdioTransport(mcp.StdioTransportConfig{
        Command: "npx",
        Args:    []string{"-y", "@modelcontextprotocol/server-everything"},
    })

    client := mcp.NewMCPClient(transport, mcp.MCPClientConfig{
        ClientName:    "my-app",
        ClientVersion: "1.0.0",
    })

    // Connect to server
    ctx := context.Background()
    if err := client.Connect(ctx); err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    // Get serializable tools
    tools, err := client.GetSerializableTools(ctx)
    if err != nil {
        log.Fatal(err)
    }

    // Tools can now be serialized and stored
    data, _ := json.MarshalIndent(tools, "", "  ")
    fmt.Printf("Serialized tools:\n%s\n", string(data))
}

Storing Tool Definitions

Tool definitions can be cached to avoid repeated server queries:

import (
    "encoding/json"
    "os"
)

// Cache tools to file
func cacheTools(tools *mcp.ListToolsResult, filename string) error {
    data, err := json.Marshal(tools)
    if err != nil {
        return err
    }
    return os.WriteFile(filename, data, 0644)
}

// Load tools from cache
func loadCachedTools(filename string) (*mcp.ListToolsResult, error) {
    data, err := os.ReadFile(filename)
    if err != nil {
        return nil, err
    }

    var tools mcp.ListToolsResult
    if err := json.Unmarshal(data, &tools); err != nil {
        return nil, err
    }

    return &tools, nil
}

// Usage
tools, err := client.GetSerializableTools(ctx)
if err != nil {
    log.Fatal(err)
}

// Cache for later use
if err := cacheTools(tools, "mcp-tools-cache.json"); err != nil {
    log.Printf("Warning: Failed to cache tools: %v", err)
}

Transmitting Tool Definitions

Tool definitions can be sent over the network:

import (
    "bytes"
    "encoding/json"
    "net/http"
)

// Send tools to remote service
func sendToolsToService(tools *mcp.ListToolsResult, url string) error {
    data, err := json.Marshal(tools)
    if err != nil {
        return err
    }

    resp, err := http.Post(url, "application/json", bytes.NewReader(data))
    if err != nil {
        return err
    }
    defer resp.Body.Close()

    return nil
}

// Usage
tools, err := client.GetSerializableTools(ctx)
if err != nil {
    log.Fatal(err)
}

err = sendToolsToService(tools, "https://api.example.com/mcp-tools")
if err != nil {
    log.Printf("Failed to send tools: %v", err)
}

Pagination Support

When MCP servers have many tools, results may be paginated:

func getAllTools(client *mcp.MCPClient, ctx context.Context) ([]mcp.MCPTool, error) {
    var allTools []mcp.MCPTool

    // Get first page
    result, err := client.GetSerializableTools(ctx)
    if err != nil {
        return nil, err
    }

    allTools = append(allTools, result.Tools...)

    // Handle pagination if present.
    if result.NextCursor != "" {
        log.Printf("More tools available (cursor: %s)", result.NextCursor)
    }

    return allTools, nil
}

Comparison: ListTools vs GetSerializableTools

The SDK provides two methods for retrieving tools:

Method	Return Type	Use Case
ListTools()	[]MCPTool	Convenience method for immediate use
GetSerializableTools()	*ListToolsResult	Full result with pagination support for storage/transmission

// Convenience method - just the tools
tools, err := client.ListTools(ctx)
// Returns: []MCPTool

// Serialization method - complete result
result, err := client.GetSerializableTools(ctx)
// Returns: *ListToolsResult with Tools + NextCursor

Use Cases

1. Tool Registry Service

Build a centralized registry of available tools:

type ToolRegistry struct {
    tools map[string]*mcp.ListToolsResult
}

func (r *ToolRegistry) RegisterServer(serverName string, tools *mcp.ListToolsResult) {
    r.tools[serverName] = tools
}

func (r *ToolRegistry) GetAllTools() []*mcp.ListToolsResult {
    var all []*mcp.ListToolsResult
    for _, tools := range r.tools {
        all = append(all, tools)
    }
    return all
}

2. Offline Tool Discovery

Cache tools for offline browsing:

func discoverAndCache(servers []string) error {
    for _, server := range servers {
        client := connectToServer(server)
        tools, err := client.GetSerializableTools(ctx)
        if err != nil {
            log.Printf("Failed to get tools from %s: %v", server, err)
            continue
        }

        filename := fmt.Sprintf("tools-%s.json", server)
        if err := cacheTools(tools, filename); err != nil {
            log.Printf("Failed to cache tools for %s: %v", server, err)
        }
    }
    return nil
}

3. Tool Versioning

Track tool changes over time:

type ToolSnapshot struct {
    Timestamp time.Time              `json:"timestamp"`
    Tools     *mcp.ListToolsResult   `json:"tools"`
}

func snapshotTools(client *mcp.MCPClient) (*ToolSnapshot, error) {
    tools, err := client.GetSerializableTools(context.Background())
    if err != nil {
        return nil, err
    }

    return &ToolSnapshot{
        Timestamp: time.Now(),
        Tools:     tools,
    }, nil
}

Best Practices

1. Cache tool definitions: Avoid repeated queries by caching results
2. Handle pagination: Check for NextCursor and implement pagination when needed
3. Validate after deserialization: Ensure tools loaded from cache are still valid
4. Version your cache: Include timestamps or version numbers in cached data
5. Implement TTL: Refresh cached tools periodically to catch updates

Error Handling

tools, err := client.GetSerializableTools(ctx)
if err != nil {
    var mcpErr *mcp.MCPClientError
    switch {
    case errors.Is(err, context.DeadlineExceeded):
        log.Fatal("Timeout getting tools")
    case errors.As(err, &mcpErr):
        log.Fatalf("MCP error %d: %s", mcpErr.Code, mcpErr.Message)
    default:
        log.Fatalf("Failed to get tools: %v", err)
    }
}

See Also

• MCP Integration Guide
• MCP Client API
• Tool Execution