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

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"
    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: "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: [])
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


See Alsoยถ