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:
- Reads the catalog file on startup
- Registers all enabled servers
- Starts health checks (if enabled)
- 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:
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:
-
Check that catalog is enabled:
-
Verify catalog file path:
-
Check gateway logs for parsing errors:
-
Validate YAML syntax:
Servers Not Appearing in Catalogยถ
Symptoms: Catalog servers don't appear in the Admin UI
Solutions:
-
Verify server URLs are accessible:
-
Check server entry has all required fields:
-
Validate YAML syntax:
Authentication Errorsยถ
Symptoms: 401/403 errors when accessing catalog servers after registration
Solutions:
- Verify the
auth_type
matches the server's requirements: "Open"
- No authentication required"API Key"
- Requires API key (setrequires_api_key: true
)-
"OAuth2.1"
- Requires OAuth configuration -
For OAuth servers, ensure you complete the OAuth flow after registration via the Admin UI
-
For API Key servers, provide the API key during registration
See Alsoยถ
- Configuration Reference - Complete configuration guide
- SSO Configuration - Authentication and SSO setup
- Export/Import - Bulk operations and data migration
- Observability - Monitoring and tracing