bridge_config_schema.json•22.6 kB
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "MCP Foxxy Bridge Configuration Schema",
"description": "Configuration schema for MCP Foxxy Bridge one-to-many server connectivity with OAuth 2.0 support",
"type": "object",
"properties": {
"$schema": {
"type": "string",
"description": "JSON Schema reference for IDE support and validation"
},
"mcpServers": {
"type": "object",
"description": "Collection of MCP servers to bridge",
"patternProperties": {
"^[a-zA-Z0-9_-]+$": {
"type": "object",
"description": "MCP server configuration",
"properties": {
"enabled": {
"type": "boolean",
"default": true,
"description": "Whether this server is enabled"
},
"command": {
"type": "string",
"description": "Command to execute the MCP server"
},
"args": {
"type": "array",
"items": {
"type": "string"
},
"default": [],
"description": "Command line arguments for the MCP server"
},
"env": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"default": {},
"description": "Environment variables for the MCP server"
},
"timeout": {
"type": "number",
"default": 60,
"description": "Connection timeout in seconds"
},
"retryAttempts": {
"type": "number",
"default": 3,
"description": "Number of retry attempts on connection failure"
},
"retryDelay": {
"type": "number",
"default": 1000,
"description": "Delay between retry attempts in milliseconds"
},
"healthCheck": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"default": true,
"description": "Whether to perform health checks"
},
"interval": {
"type": "number",
"default": 30000,
"description": "Health check interval in milliseconds"
},
"timeout": {
"type": "number",
"default": 5000,
"description": "Health check timeout in milliseconds"
},
"keepAliveInterval": {
"type": "number",
"default": 60000,
"description": "Keep-alive ping interval in milliseconds"
},
"keepAliveTimeout": {
"type": "number",
"default": 10000,
"description": "Keep-alive ping timeout in milliseconds"
},
"maxConsecutiveFailures": {
"type": "number",
"default": 3,
"description": "Maximum consecutive failures before marking server as failed"
},
"autoRestart": {
"type": "boolean",
"default": true,
"description": "Whether to automatically restart failed servers"
},
"restartDelay": {
"type": "number",
"default": 5000,
"description": "Delay before restart attempt in milliseconds"
},
"maxRestartAttempts": {
"type": "number",
"default": 5,
"description": "Maximum restart attempts before giving up"
},
"operation": {
"type": "string",
"enum": ["list_tools", "list_resources", "list_prompts", "call_tool", "read_resource", "get_prompt", "ping", "health", "status"],
"default": "list_tools",
"description": "MCP operation to use for health checks"
},
"toolName": {
"type": "string",
"description": "Specific tool name if operation is 'call_tool'"
},
"toolArguments": {
"type": "object",
"description": "Arguments for tool calls"
},
"resourceUri": {
"type": "string",
"description": "Resource URI if operation is 'read_resource'"
},
"promptName": {
"type": "string",
"description": "Prompt name if operation is 'get_prompt'"
},
"promptArguments": {
"type": "object",
"description": "Arguments for prompt calls"
},
"httpPath": {
"type": "string",
"description": "Custom HTTP path for health checks"
},
"httpMethod": {
"type": "string",
"enum": ["GET", "POST", "PUT", "DELETE"],
"default": "GET",
"description": "HTTP method for health checks"
},
"expectedStatus": {
"type": "number",
"default": 200,
"description": "Expected HTTP status code for health checks"
},
"expectedContent": {
"type": "string",
"description": "Expected content pattern for health checks"
}
},
"default": {
"enabled": true,
"interval": 30000,
"timeout": 5000
}
},
"toolNamespace": {
"type": "string",
"description": "Optional namespace prefix for tools from this server"
},
"resourceNamespace": {
"type": "string",
"description": "Optional namespace prefix for resources from this server"
},
"promptNamespace": {
"type": "string",
"description": "Optional namespace prefix for prompts from this server"
},
"priority": {
"type": "number",
"default": 100,
"description": "Priority for conflict resolution (lower = higher priority)"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"default": [],
"description": "Tags for organizing and filtering servers"
},
"transport": {
"type": "string",
"enum": ["stdio", "sse", "http"],
"default": "stdio",
"description": "Transport mechanism for server communication. OAuth is supported for SSE and HTTP transports."
},
"type": {
"type": "string",
"enum": ["stdio", "sse", "http"],
"default": "stdio",
"description": "Legacy alias for transport mechanism"
},
"url": {
"type": "string",
"description": "URL for SSE/HTTP transport (required for non-stdio transports). OAuth tokens will be automatically included in requests."
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"default": {},
"description": "HTTP headers for SSE/HTTP transports (OAuth Authorization header is automatically added when OAuth is enabled)"
},
"log_level": {
"type": "string",
"enum": ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
"default": "ERROR",
"description": "Logging level for this server"
},
"working_directory": {
"type": ["string", "null"],
"description": "Working directory for the MCP server process"
},
"verify_ssl": {
"type": "boolean",
"default": true,
"description": "Whether to verify SSL/TLS certificates for HTTPS connections"
},
"authentication": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["bearer", "api_key", "basic"],
"description": "Authentication type"
},
"token": {
"type": "string",
"description": "Bearer token (for bearer auth)"
},
"key": {
"type": "string",
"description": "API key (for api_key auth)"
},
"header": {
"type": "string",
"default": "X-API-Key",
"description": "Header name for API key (for api_key auth)"
},
"username": {
"type": "string",
"description": "Username (for basic auth)"
},
"password": {
"type": "string",
"description": "Password (for basic auth)"
}
},
"description": "Authentication configuration"
},
"oauth": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"default": false,
"description": "Enable OAuth 2.0 authentication"
},
"issuer": {
"type": "string",
"description": "OAuth issuer URL for discovery (e.g., https://auth.atlassian.com)"
},
"verify_ssl": {
"type": "boolean",
"default": true,
"description": "Whether to verify SSL/TLS certificates for OAuth endpoints"
},
"keep_alive_interval": {
"type": "number",
"default": 20000,
"description": "Keep-alive ping interval for OAuth servers in milliseconds"
},
"token_refresh_interval": {
"type": "number",
"default": 1800000,
"description": "Proactive token refresh interval in milliseconds (30 minutes)"
},
"connection_check_interval": {
"type": "number",
"default": 10000,
"description": "Connection health check interval in milliseconds"
},
"client_id": {
"type": "string",
"description": "OAuth client ID (for static configuration)"
},
"authorization_url": {
"type": "string",
"description": "OAuth authorization URL (for static configuration)"
},
"token_url": {
"type": "string",
"description": "OAuth token URL (for static configuration)"
},
"type": {
"type": "string",
"enum": ["dynamic", "static"],
"default": "dynamic",
"description": "OAuth flow type - dynamic uses issuer discovery, static uses explicit URLs"
}
},
"description": "OAuth 2.0 configuration for server authentication"
},
"oauth_config": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"default": false,
"description": "Enable OAuth 2.0 authentication (legacy field)"
},
"issuer": {
"type": "string",
"description": "OAuth issuer URL for discovery (legacy field)"
},
"verify_ssl": {
"type": "boolean",
"default": true,
"description": "Whether to verify SSL/TLS certificates (legacy field)"
},
"type": {
"type": "string",
"enum": ["dynamic", "static"],
"default": "dynamic",
"description": "OAuth flow type (legacy field - use 'oauth' instead)"
}
},
"description": "Legacy OAuth configuration (use 'oauth' instead for new configurations)"
},
"security": {
"type": "object",
"properties": {
"read_only_mode": {
"type": "boolean",
"description": "Override global read-only mode for this server (null inherits from bridge)"
},
"tool_security": {
"type": "object",
"properties": {
"allow_patterns": {
"type": "array",
"items": {
"type": "string"
},
"default": [],
"description": "Glob/regex patterns for allowed tool names"
},
"block_patterns": {
"type": "array",
"items": {
"type": "string"
},
"default": [],
"description": "Glob/regex patterns for blocked tool names"
},
"allow_tools": {
"type": "array",
"items": {
"type": "string"
},
"default": [],
"description": "Specific tool names to allow"
},
"block_tools": {
"type": "array",
"items": {
"type": "string"
},
"default": [],
"description": "Specific tool names to block"
},
"classification_overrides": {
"type": "object",
"additionalProperties": {
"type": "string",
"enum": ["read", "write", "unknown"]
},
"default": {},
"description": "Manual classification overrides for specific tools"
}
},
"default": {
"allow_patterns": [],
"block_patterns": [],
"allow_tools": [],
"block_tools": [],
"classification_overrides": {}
}
}
},
"default": {}
}
},
"additionalProperties": false,
"anyOf": [
{
"description": "STDIO transport requires command",
"properties": {
"transport": {
"const": "stdio"
}
},
"required": ["command"]
},
{
"description": "SSE transport requires URL (supports OAuth authentication)",
"properties": {
"transport": {
"const": "sse"
}
},
"required": ["url"]
},
{
"description": "HTTP transport requires URL (supports OAuth authentication)",
"properties": {
"transport": {
"const": "http"
}
},
"required": ["url"]
},
{
"description": "Default (stdio) transport requires command",
"not": {
"properties": {
"transport": {
"enum": ["sse", "http"]
}
}
},
"required": ["command"]
}
]
}
}
},
"bridge": {
"type": "object",
"description": "Bridge-specific configuration",
"properties": {
"conflictResolution": {
"type": "string",
"enum": ["priority", "namespace", "first", "error"],
"default": "namespace",
"description": "How to handle tool/resource name conflicts"
},
"defaultNamespace": {
"type": "boolean",
"default": true,
"description": "Whether to add server name as namespace by default"
},
"aggregation": {
"type": "object",
"properties": {
"tools": {
"type": "boolean",
"default": true,
"description": "Whether to aggregate tools from all servers"
},
"resources": {
"type": "boolean",
"default": true,
"description": "Whether to aggregate resources from all servers"
},
"prompts": {
"type": "boolean",
"default": true,
"description": "Whether to aggregate prompts from all servers"
}
},
"default": {
"tools": true,
"resources": true,
"prompts": true
}
},
"failover": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"default": true,
"description": "Whether to enable failover for failed servers"
},
"maxFailures": {
"type": "number",
"default": 3,
"description": "Maximum failures before marking server as unavailable"
},
"recoveryInterval": {
"type": "number",
"default": 60000,
"description": "Interval to attempt recovery in milliseconds"
}
},
"default": {
"enabled": true,
"maxFailures": 3,
"recoveryInterval": 60000
}
},
"port": {
"type": "number",
"default": 9000,
"description": "Port for the bridge HTTP server"
},
"oauth_port": {
"type": "number",
"default": 8090,
"description": "Port for OAuth callback server (used for all server OAuth flows)"
},
"allow_command_substitution": {
"type": "boolean",
"default": false,
"description": "Allow command substitution in configuration values (useful for OAuth secrets from credential managers)"
},
"allowed_commands": {
"type": "array",
"items": {
"type": "string"
},
"default": [],
"description": "Allowed commands for command substitution (when enabled)"
},
"security": {
"type": "object",
"properties": {
"read_only_mode": {
"type": "boolean",
"default": true,
"description": "Global read-only mode (blocks all write tools by default)"
},
"tool_security": {
"type": "object",
"properties": {
"allow_patterns": {
"type": "array",
"items": {
"type": "string"
},
"default": [],
"description": "Global glob/regex patterns for allowed tool names"
},
"block_patterns": {
"type": "array",
"items": {
"type": "string"
},
"default": [],
"description": "Global glob/regex patterns for blocked tool names"
},
"allow_tools": {
"type": "array",
"items": {
"type": "string"
},
"default": [],
"description": "Global specific tool names to allow"
},
"block_tools": {
"type": "array",
"items": {
"type": "string"
},
"default": [],
"description": "Global specific tool names to block"
},
"classification_overrides": {
"type": "object",
"additionalProperties": {
"type": "string",
"enum": ["read", "write", "unknown"]
},
"default": {},
"description": "Global manual classification overrides for specific tools"
}
},
"default": {
"allow_patterns": [],
"block_patterns": [],
"allow_tools": [],
"block_tools": [],
"classification_overrides": {}
}
}
},
"default": {
"read_only_mode": true
}
}
},
"default": {
"conflictResolution": "namespace",
"defaultNamespace": true,
"aggregation": {
"tools": true,
"resources": true,
"prompts": true
},
"failover": {
"enabled": true,
"maxFailures": 3,
"recoveryInterval": 60000
},
"port": 9000,
"oauth_port": 8090,
"allow_command_substitution": false,
"allowed_commands": [],
"security": {
"read_only_mode": true
}
}
}
},
"required": ["mcpServers"],
"additionalProperties": false
}