go-mcp-registry

A Go SDK for the Model Context Protocol (MCP) Registry - the official registry for MCP servers.

Overview

The Model Context Protocol (MCP) enables applications to integrate with external data sources and tools. The MCP Registry serves as a central hub for discovering and retrieving MCP servers developed by the community.

This Go SDK provides an idiomatic interface to the MCP Registry API, allowing you to:

• Discover MCP servers with search and filtering capabilities
• Retrieve server details including installation packages and configurations
• Handle pagination automatically or manually
• Track rate limits and handle API errors gracefully
• Find specific versions with flexible version resolution
• Access comprehensive metadata for each server

What's New in v0.6.0

This release includes API v0.1 migration and significant testing improvements:

• API v0.1 Support: All endpoints now use the stable v0.1 API path
• Enhanced Testing: Test coverage increased from 73.5% to 94.2%
• Version Options: Get() method now supports version-specific retrieval via ServerGetOptions
• Breaking Change: Internal endpoint migration (no code changes required for users)

For complete details, see the CHANGELOG.

Installation

go get github.com/leefowlercu/go-mcp-registry

Requirements: Go 1.24 or later

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/leefowlercu/go-mcp-registry/mcp"
)

func main() {
    // Create a client
    client := mcp.NewClient(nil)
    ctx := context.Background()

    // List servers
    servers, _, err := client.Servers.List(ctx, &mcp.ServerListOptions{
        ListOptions: mcp.ListOptions{Limit: 10},
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Found %d servers:\n", len(servers.Servers))
    for _, serverResponse := range servers.Servers {
        fmt.Printf("- %s (v%s): %s\n", serverResponse.Server.Name, serverResponse.Server.Version, serverResponse.Server.Description)
    }

    // Get all versions of a server by name
    gmailServers, _, err := client.Servers.ListVersionsByName(ctx, "ai.waystation/gmail")
    if err != nil {
        log.Fatal(err)
    }
    if len(gmailServers) > 0 {
        fmt.Printf("\nGmail server latest version: %s\n", gmailServers[0].Version)
    }
}

Usage Guide

Client Configuration

import (
    "net/http"
    "time"
    "github.com/leefowlercu/go-mcp-registry/mcp"
)

// Default client
client := mcp.NewClient(nil)

// Custom HTTP client with timeout
httpClient := &http.Client{
    Timeout: 60 * time.Second,
}
client := mcp.NewClient(httpClient)

Listing Servers

// Basic listing
servers, resp, err := client.Servers.List(ctx, nil)

// With search and filtering
opts := &mcp.ServerListOptions{
    Search: "github",           // Search server names
    Version: "latest",          // Only latest versions
    ListOptions: mcp.ListOptions{
        Limit: 20,              // Page size
    },
}
servers, resp, err := client.Servers.List(ctx, opts)

// Get all servers (handles pagination automatically)
allServers, _, err := client.Servers.ListAll(ctx, nil)

Getting Servers by Name

// Get latest version using Get()
server, _, err := client.Servers.Get(ctx, "ai.waystation/gmail", nil)

// Get specific version using Get()
server, _, err := client.Servers.Get(ctx, "ai.waystation/gmail", &mcp.ServerGetOptions{
    Version: "1.0.0",
})

// Get all versions of a server by name
servers, _, err := client.Servers.ListVersionsByName(ctx, "ai.waystation/gmail")

// Get latest version using name filter
server, _, err := client.Servers.GetByNameLatest(ctx, "ai.waystation/gmail")

// Get specific version via dedicated endpoint (most performant)
server, _, err := client.Servers.GetByNameExactVersion(ctx, "ai.waystation/gmail", "0.3.1")

// Get latest active version (uses semantic versioning)
server, _, err := client.Servers.GetByNameLatestActiveVersion(ctx, "ai.waystation/gmail")

Accessing Registry Metadata

Registry metadata (Status, PublishedAt, UpdatedAt, IsLatest) is available when using List() methods:

servers, _, err := client.Servers.List(ctx, nil)
if err != nil {
    log.Fatal(err)
}

for _, serverResponse := range servers.Servers {
    // Access server data
    fmt.Printf("Name: %s\n", serverResponse.Server.Name)
    fmt.Printf("Version: %s\n", serverResponse.Server.Version)

    // Access metadata (if available)
    if serverResponse.Meta.Official != nil {
        fmt.Printf("Status: %s\n", serverResponse.Meta.Official.Status)
        fmt.Printf("Published: %v\n", serverResponse.Meta.Official.PublishedAt)
        fmt.Printf("Updated: %v\n", serverResponse.Meta.Official.UpdatedAt)
        fmt.Printf("Is Latest: %v\n", serverResponse.Meta.Official.IsLatest)
    }
}

Note: Get() methods return ServerJSON without metadata. Use List() methods to access registry metadata.

Manual Pagination

opts := &mcp.ServerListOptions{
    ListOptions: mcp.ListOptions{Limit: 50},
}

for {
    resp, _, err := client.Servers.List(ctx, opts)
    if err != nil {
        break
    }

    // Process servers
    for _, serverResponse := range resp.Servers {
        fmt.Printf("Server: %s\n", serverResponse.Server.Name)
    }

    // Check for more pages
    if resp.Metadata.NextCursor == "" {
        break
    }
    opts.Cursor = resp.Metadata.NextCursor
}

Error Handling

servers, resp, err := client.Servers.List(ctx, nil)
if err != nil {
    // Check for rate limiting
    if rateLimitErr, ok := err.(*mcp.RateLimitError); ok {
        fmt.Printf("Rate limited. Reset at: %v\n", rateLimitErr.Rate.Reset)
        return
    }

    // Check for API errors
    if apiErr, ok := err.(*mcp.ErrorResponse); ok {
        fmt.Printf("API error: %v\n", apiErr.Message)
        return
    }

    log.Fatal(err)
}

// Check rate limit info
if resp.Rate.Limit > 0 {
    fmt.Printf("Rate limit: %d/%d remaining\n", resp.Rate.Remaining, resp.Rate.Limit)
}

API Methods Reference

For detailed documentation, see the Go Reference.

Examples

This repository includes working examples in the examples/ directory:

• examples/list/ - List servers with search, filtering, and metadata access
• examples/get/ - Get server details with version options and error handling
• examples/paginate/ - Manual and automatic pagination
• examples/version/ - Version-specific retrieval using GetByNameExactVersion
• examples/updated/ - Timestamp-based filtering with ListByUpdatedSince

Run examples:

go run ./examples/list/
go run ./examples/get/ "ai.waystation/gmail"
go run ./examples/get/ "ai.waystation/gmail" "1.0.0"
go run ./examples/paginate/
go run ./examples/version/ "ai.waystation/gmail"
go run ./examples/updated/ 24

Development

Running Tests

Current test coverage: 94.2%

# Unit tests
go test ./...

# With coverage
go test -cover ./...

# Integration tests (requires network)
INTEGRATION_TESTS=true go test ./test/integration/

# Specific test
go test -v ./mcp -run TestServersService_ListVersionsByName

Building

# Build all packages
go build ./...

# Build examples
go build ./examples/...

# Format code
gofmt -s -w .

# Lint
go vet ./...

Architecture

This SDK follows the service-oriented architecture pattern established by google/go-github, organizing API endpoints into logical service groups:

• Client - Main entry point with HTTP client management
• ServersService - All server-related operations

The SDK imports and reuses official types from the MCP Registry repository to ensure perfect API compatibility without type conversion overhead.

Links

• MCP Protocol: https://modelcontextprotocol.io/
• MCP Registry: https://registry.modelcontextprotocol.io/
• API Documentation: https://registry.modelcontextprotocol.io/docs
• Registry Repository: https://github.com/modelcontextprotocol/registry

License

MIT License - see LICENSE file for details.