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:
- 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_typematches 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
Transport Type IssuesΒΆ
Symptoms: WebSocket servers fail to connect after registration
Solutions:
-
Explicitly specify the
transportfield in your catalog YAML: -
Verify URL scheme matches transport type:
- WebSocket:
ws://orwss:// - SSE:
http://orhttps://with/ssepath - HTTP:
http://orhttps://with/mcppath
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
transportfield in catalog YAML (SSE,WEBSOCKET,STREAMABLEHTTP) - Auto-Detection: Automatically detects transport from URL if not specified
ws://orwss://βWEBSOCKET- URLs ending in
/sseβSSE - URLs with
/mcppath β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ΒΆ
- Configuration Reference - Complete configuration guide
- SSO Configuration - Authentication and SSO setup
- Export/Import - Bulk operations and data migration
- Observability - Monitoring and tracing