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

Method	Description
List(ctx, opts)	List servers with pagination and filtering
Get(ctx, serverName, opts)	Get server by name with optional version
ListAll(ctx, opts)	Get all servers (automatic pagination)
ListVersionsByName(ctx, name)	Get all versions of a server by name
ListByName(ctx, name)	Get all versions with exact name match
ListByUpdatedSince(ctx, since)	Get servers updated since timestamp
GetByNameLatest(ctx, name)	Get latest version using API filter
GetByNameExactVersion(ctx, name, version)	Get specific version via dedicated endpoint
GetByNameLatestActiveVersion(ctx, name)	Get latest active version by semver

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.