Skip to content

MCP Server CatalogΒΆ

πŸ†• New in v0.7.0: The MCP Server Catalog feature allows you to define a catalog of pre-configured MCP servers in a YAML file for easy discovery, registration, and management via the Admin UI and API.

OverviewΒΆ

The MCP Server Catalog provides a declarative way to define and manage MCP servers, reducing manual configuration and enabling automated server registration and health monitoring.

Key Features:

  • πŸ“ Declarative Configuration: Define servers in YAML format
  • πŸ” Automatic Discovery: Servers are automatically registered on startup
  • πŸ’š Health Monitoring: Automatic health checks for catalog servers
  • πŸ—‚οΈ Categorization: Organize servers with tags and descriptions
  • ⚑ Fast Onboarding: Quickly add new MCP servers without API calls

ConfigurationΒΆ

Environment VariablesΒΆ

Configure the catalog feature using these environment variables:

# Enable MCP server catalog feature (default: true)
MCPGATEWAY_CATALOG_ENABLED=true

# Path to catalog configuration file (default: mcp-catalog.yml)
MCPGATEWAY_CATALOG_FILE=mcp-catalog.yml

# Automatically health check catalog servers (default: true)
MCPGATEWAY_CATALOG_AUTO_HEALTH_CHECK=true

# Catalog cache TTL in seconds (default: 3600)
MCPGATEWAY_CATALOG_CACHE_TTL=3600

# Number of catalog servers to display per page (default: 12)
MCPGATEWAY_CATALOG_PAGE_SIZE=12

Catalog File FormatΒΆ

The catalog file uses YAML format with the following structure:

Basic ExampleΒΆ

# mcp-catalog.yml
catalog_servers:

  - id: "time-server"
    name: "Time Server"
    category: "Utilities"
    url: "http://localhost:9000/sse"
    auth_type: "Open"
    provider: "Local"
    description: "Fast time server providing current time utilities"
    requires_api_key: false
    tags:

      - "utilities"
      - "time"
      - "development"

  - id: "git-server"
    name: "Git Server"
    category: "Software Development"
    url: "http://localhost:9001/sse"
    auth_type: "Open"
    provider: "Local"
    description: "Git repository MCP server"
    requires_api_key: false
    tags:

      - "git"
      - "version-control"
      - "development"

# Optional: Categories for UI filtering
categories:

  - Utilities
  - Software Development

# Optional: Auth types for UI filtering
auth_types:

  - Open
  - OAuth2.1
  - API Key

Full Example with All FieldsΒΆ

# Production MCP Server Catalog
catalog_servers:

  - id: "production-time-server"
    name: "Production Time Server"
    category: "Utilities"
    url: "https://time.api.example.com/sse"
    transport: "SSE"  # Optional: Explicitly specify transport type
    auth_type: "OAuth2.1"
    provider: "Internal Platform"
    description: "Production time server with geo-replication"
    requires_api_key: false
    secure: true
    tags:

      - "production"
      - "utilities"
      - "time"
      - "geo-replicated"
    logo_url: "https://static.example.com/time-server-logo.png"
    documentation_url: "https://docs.example.com/time-server"

  - id: "websocket-server"
    name: "WebSocket MCP Server"
    category: "Development Tools"
    url: "wss://api.example.com/mcp"
    transport: "WEBSOCKET"  # Specify WebSocket transport
    auth_type: "API Key"
    provider: "Internal Platform"
    description: "Real-time MCP server using WebSocket protocol"
    requires_api_key: true
    secure: true
    tags:

      - "production"
      - "websocket"
      - "real-time"

  - id: "database-server"
    name: "Database Server"
    category: "Database"
    url: "https://db.api.example.com/sse"
    auth_type: "OAuth2.1"
    provider: "Internal Platform"
    description: "Database query and management MCP server"
    requires_api_key: false
    secure: true
    tags:

      - "production"
      - "database"
      - "postgresql"
    documentation_url: "https://docs.example.com/db-server"

  - id: "github-api"
    name: "GitHub"
    category: "Software Development"
    url: "https://api.githubcopilot.com/mcp"
    auth_type: "OAuth2.1"
    provider: "GitHub"
    description: "Version control and collaborative software development"
    requires_api_key: false
    secure: true
    tags:

      - "development"
      - "git"
      - "version-control"
    logo_url: "https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png"
    documentation_url: "https://docs.github.com"

categories:

  - Utilities
  - Database
  - Software Development

auth_types:

  - OAuth2.1
  - API Key
  - Open

Field ReferenceΒΆ

Root FieldsΒΆ

Field Type Required Description
catalog_servers array Yes List of MCP server definitions
categories array No List of available categories for UI filtering
auth_types array No List of available auth types for UI filtering

Catalog Server FieldsΒΆ

Based on the CatalogServer schema (schemas.py:5371-5387):

Field Type Required Description
id string Yes Unique identifier for the catalog server
name string Yes Display name of the server
category string Yes Server category (e.g., "Project Management", "Software Development")
url string Yes Server endpoint URL
auth_type string Yes Authentication type (e.g., "OAuth2.1", "API Key", "Open")
provider string Yes Provider/vendor name
description string Yes Server description
requires_api_key boolean No Whether API key is required (default: false)
secure boolean No Whether additional security is required (default: false)
tags array No Tags for categorization (default: [])
transport string No Transport type: SSE, STREAMABLEHTTP, or WEBSOCKET (auto-detected if not specified)
logo_url string No URL to server logo/icon
documentation_url string No URL to server documentation
is_registered boolean No Whether server is already registered (set by system)
is_available boolean No Whether server is currently available (default: true)

UsageΒΆ

Automatic Registration on StartupΒΆ

When MCPGATEWAY_CATALOG_ENABLED=true, the gateway automatically:

  1. Reads the catalog file on startup
  2. Registers all enabled servers
  3. Starts health checks (if enabled)
  4. Makes servers available via the Admin UI and API

Manual Catalog ReloadΒΆ

Reload the catalog without restarting the gateway:

# Using the CLI
mcpgateway catalog reload

# Or via API
curl -X POST -H "Authorization: Bearer $TOKEN" \
  http://localhost:4444/admin/catalog/reload

Listing Catalog ServersΒΆ

# Via CLI
mcpgateway catalog list

# Via API
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:4444/admin/catalog/servers

Filtering by TagsΒΆ

# List all production servers
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:4444/admin/catalog/servers?tag=production"

# List all database servers
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:4444/admin/catalog/servers?tag=database"

Best PracticesΒΆ

1. Use Consistent NamingΒΆ

Use clear, descriptive IDs and names:

catalog_servers:

  - id: "github-production"  # βœ… Good: Clear and unique
    name: "GitHub Production"
    # ... other fields

2. Organize with TagsΒΆ

Use consistent tagging for easier filtering and management:

catalog_servers:

  - id: "prod-db-server"
    name: "Production Database"
    category: "Database"
    tags:

      - "production"      # Environment
      - "postgresql"      # Technology
      - "critical"        # Priority

3. Categorize ClearlyΒΆ

Use standard categories that match your organization:

categories:

  - "Software Development"
  - "Database"
  - "Productivity"
  - "Project Management"

4. Document Server MetadataΒΆ

Include logo and documentation URLs for better UX:

catalog_servers:

  - id: "time-server"
    name: "Time Server"
    description: "Provides current time utilities with geo-replication"
    documentation_url: "https://docs.example.com/time-server"
    logo_url: "https://static.example.com/logos/time-server.png"

ExamplesΒΆ

Development EnvironmentΒΆ

# mcp-catalog.dev.yml
catalog_servers:

  - id: "local-time"
    name: "Local Time Server"
    category: "Utilities"
    url: "http://localhost:9000/sse"
    auth_type: "Open"
    provider: "Local"
    description: "Local development time server"
    requires_api_key: false
    tags: ["dev", "utilities", "time"]

  - id: "local-git"
    name: "Local Git Server"
    category: "Software Development"
    url: "http://localhost:9001/sse"
    auth_type: "Open"
    provider: "Local"
    description: "Local Git MCP server"
    requires_api_key: false
    tags: ["dev", "git", "version-control"]

categories:

  - "Utilities"
  - "Software Development"

auth_types:

  - "Open"

Production EnvironmentΒΆ

# mcp-catalog.prod.yml
catalog_servers:

  - id: "prod-time-api"
    name: "Production Time API"
    category: "Utilities"
    url: "https://time.api.example.com/sse"
    auth_type: "OAuth2.1"
    provider: "Platform Engineering"
    description: "Production time API with geo-replication and high availability"
    requires_api_key: false
    secure: true
    tags: ["production", "critical", "utilities"]
    documentation_url: "https://docs.example.com/time-api"

  - id: "prod-database-api"
    name: "Production Database API"
    category: "Database"
    url: "https://db.api.example.com/sse"
    auth_type: "OAuth2.1"
    provider: "Platform Engineering"
    description: "Production PostgreSQL database API with RBAC"
    requires_api_key: false
    secure: true
    tags: ["production", "critical", "database", "postgresql"]
    documentation_url: "https://docs.example.com/db-api"

  - id: "stripe-payments"
    name: "Stripe Payments"
    category: "Payments"
    url: "https://mcp.stripe.com/"
    auth_type: "API Key"
    provider: "Stripe"
    description: "Payment processing and financial infrastructure"
    requires_api_key: true
    secure: true
    tags: ["production", "payments", "finance"]
    logo_url: "https://stripe.com/img/v3/home/social.png"
    documentation_url: "https://stripe.com/docs"

categories:

  - "Utilities"
  - "Database"
  - "Payments"

auth_types:

  - "OAuth2.1"
  - "API Key"

TroubleshootingΒΆ

Catalog File Not LoadingΒΆ

Symptoms: Servers from catalog don't appear in the Admin UI

Solutions:

  1. Check that catalog is enabled:

    echo $MCPGATEWAY_CATALOG_ENABLED  # Should be "true"
    

  2. Verify catalog file path:

    ls -la mcp-catalog.yml  # Or your configured path
    

  3. Check gateway logs for parsing errors:

    docker logs mcpgateway | grep -i catalog
    

  4. Validate YAML syntax:

    python3 -c "import yaml; yaml.safe_load(open('mcp-catalog.yml'))"
    

Servers Not Appearing in CatalogΒΆ

Symptoms: Catalog servers don't appear in the Admin UI

Solutions:

  1. Verify server URLs are accessible:

    curl -v http://localhost:9000/sse
    

  2. Check server entry has all required fields:

    catalog_servers:
    
      - id: "my-server"          # Required
        name: "My Server"        # Required
        category: "Utilities"    # Required
        url: "http://..."        # Required
        auth_type: "Open"        # Required
        provider: "MyProvider"   # Required
        description: "..."       # Required
    

  3. Validate YAML syntax:

    python3 -c "import yaml; print(yaml.safe_load(open('mcp-catalog.yml')))"
    

Authentication ErrorsΒΆ

Symptoms: 401/403 errors when accessing catalog servers after registration

Solutions:

  1. Verify the auth_type matches the server's requirements:
  2. "Open" - No authentication required
  3. "API Key" - Requires API key (set requires_api_key: true)
  4. "OAuth2.1" - Requires OAuth configuration

  5. For OAuth servers, ensure you complete the OAuth flow after registration via the Admin UI

  6. For API Key servers, provide the API key during registration

Transport Type IssuesΒΆ

Symptoms: WebSocket servers fail to connect after registration

Solutions:

  1. Explicitly specify the transport field in your catalog YAML:

    catalog_servers:
    
      - id: "websocket-server"
        url: "wss://api.example.com/mcp"
        transport: "WEBSOCKET"  # Explicitly set transport
    

  2. Verify URL scheme matches transport type:

  3. WebSocket: ws:// or wss://
  4. SSE: http:// or https:// with /sse path
  5. HTTP: http:// or https:// with /mcp path

Recent Improvements (v0.8.0)ΒΆ

Enhanced UI FeaturesΒΆ

The catalog UI now includes several UX improvements:

  • πŸ”„ Refresh Button: Manually refresh the catalog without page reload
  • πŸ” Debounced Search: 300ms debounce on search input for better performance
  • πŸ“ Custom Server Names: Ability to specify custom names when registering servers
  • πŸ“„ Pagination with Filters: Filter parameters preserved when navigating pages
  • ⚑ Better Error Messages: User-friendly error messages for common issues (connection, auth, SSL, etc.)
  • πŸ” OAuth Support: OAuth servers can be registered without credentials and configured later

Transport Type DetectionΒΆ

The catalog now supports:

  • Explicit Transport: Specify transport field in catalog YAML (SSE, WEBSOCKET, STREAMABLEHTTP)
  • Auto-Detection: Automatically detects transport from URL if not specified
  • ws:// or wss:// β†’ WEBSOCKET
  • URLs ending in /sse β†’ SSE
  • URLs with /mcp path β†’ STREAMABLEHTTP
  • Default fallback β†’ SSE

Authentication ImprovementsΒΆ

  • Custom Auth Headers: Properly mapped as list of header key-value pairs
  • OAuth Registration: OAuth servers can be registered in "disabled" state until OAuth flow is completed
  • API Key Modal: Enhanced modal with custom name field and proper authorization headers

See AlsoΒΆ