Skip to content

registry-deployment-modes.md

Latest commit

 

History

History
293 lines (214 loc) · 8.39 KB

registry-deployment-modes.md

File metadata and controls

293 lines (214 loc) · 8.39 KB

Registry Deployment and Registry Mode Configuration

This guide explains the DEPLOYMENT_MODE and REGISTRY_MODE environment variables that control how the MCP Gateway Registry operates.

Overview

The registry supports two configuration settings that control its behavior:

Setting Purpose Options
DEPLOYMENT_MODE Controls nginx/gateway integration with-gateway, registry-only
REGISTRY_MODE Controls which features are enabled (informational) full, skills-only, mcp-servers-only, agents-only

DEPLOYMENT_MODE

The DEPLOYMENT_MODE setting determines whether the registry operates as a full gateway with nginx reverse proxy integration, or as a standalone catalog/discovery service.

Mode: with-gateway (Default)

DEPLOYMENT_MODE=with-gateway

Behavior:

  • Nginx configuration is regenerated when MCP servers are registered or deleted
  • Frontend shows gateway authentication instructions (Authorization: Bearer token)
  • MCP proxy requests are routed through nginx to backend servers
  • Full gateway functionality enabled

Use when:

  • Running the registry as part of the MCP Gateway infrastructure
  • MCP servers are accessed through the nginx reverse proxy
  • You need centralized authentication and routing

Mode: registry-only

DEPLOYMENT_MODE=registry-only

Behavior:

  • Nginx configuration is NOT updated when servers are registered/deleted
  • Frontend shows "Direct Connection Mode" with proxy_pass_url
  • MCP proxy requests return 503 Service Unavailable with JSON error
  • Registry operates as a catalog/discovery service only

Use when:

  • Registry is separate from gateway infrastructure
  • Clients connect directly to MCP servers (not through gateway)
  • You only need server/agent discovery and metadata management

REGISTRY_MODE

The REGISTRY_MODE setting controls which feature flags are returned in the /api/config endpoint. This is informational and intended for frontend UI feature gating.

Note: Currently, all APIs remain active regardless of this setting. The feature flags are for UI display purposes only.

Mode Comparison Table

Mode MCP Servers Agents Skills Federation Gateway Proxy
full Enabled Enabled Enabled Enabled Based on DEPLOYMENT_MODE
skills-only Disabled Disabled Enabled Disabled Disabled
mcp-servers-only Enabled Disabled Disabled Disabled Based on DEPLOYMENT_MODE
agents-only Disabled Enabled Disabled Disabled Based on DEPLOYMENT_MODE

Mode: full (Default)

REGISTRY_MODE=full

All features enabled. The gateway_proxy flag depends on DEPLOYMENT_MODE.

Mode: skills-only

REGISTRY_MODE=skills-only

Only the skills feature flag is enabled. Intended for deployments focused solely on Agent Skills management.

Mode: mcp-servers-only

REGISTRY_MODE=mcp-servers-only

Only the MCP servers feature flag is enabled.

Mode: agents-only

REGISTRY_MODE=agents-only

Only the A2A agents feature flag is enabled.

Configuration Combinations

Valid Combinations

DEPLOYMENT_MODE REGISTRY_MODE Use Case
with-gateway full Full MCP Gateway with all features
with-gateway mcp-servers-only Gateway for MCP servers only
with-gateway agents-only Gateway for A2A agents only
registry-only full Standalone catalog with all metadata
registry-only skills-only Skills catalog only
registry-only mcp-servers-only MCP server catalog only
registry-only agents-only Agent catalog only

Invalid Combination (Auto-Corrected)

DEPLOYMENT_MODE REGISTRY_MODE Auto-Corrected To
with-gateway skills-only registry-only + skills-only

Rationale: Skills-only mode doesn't require gateway proxy functionality. The system automatically corrects this invalid combination and logs a warning.

API Configuration Endpoint

The /api/config endpoint returns the current configuration:

curl http://localhost/api/config

Example Response (with-gateway + full):

{
  "deployment_mode": "with-gateway",
  "registry_mode": "full",
  "nginx_updates_enabled": true,
  "features": {
    "mcp_servers": true,
    "agents": true,
    "skills": true,
    "federation": true,
    "gateway_proxy": true
  }
}

Example Response (registry-only + skills-only):

{
  "deployment_mode": "registry-only",
  "registry_mode": "skills-only",
  "nginx_updates_enabled": false,
  "features": {
    "mcp_servers": false,
    "agents": false,
    "skills": true,
    "federation": false,
    "gateway_proxy": false
  }
}

Environment Configuration

Docker Compose

In your .env file:

# Deployment mode: with-gateway (default) or registry-only
DEPLOYMENT_MODE=registry-only

# Registry mode: full (default), skills-only, mcp-servers-only, or agents-only
REGISTRY_MODE=skills-only

Terraform (AWS ECS)

In terraform.tfvars:

# Deployment mode
deployment_mode = "registry-only"

# Registry mode (optional, defaults to "full")
registry_mode = "skills-only"

Or via environment variables:

export TF_VAR_deployment_mode="registry-only"
export TF_VAR_registry_mode="skills-only"

Frontend Behavior

ServerConfigModal

The ServerConfigModal component adapts based on deployment_mode:

with-gateway mode:

  • Shows gateway URL constructed from current hostname
  • Displays "Authentication Required" warning
  • Shows [YOUR_AUTH_TOKEN] placeholder in configuration

registry-only mode:

  • Shows proxy_pass_url (direct server URL)
  • Displays "Direct Connection Mode" banner
  • No gateway authentication headers in configuration

Feature Flags (Future)

The features object in /api/config is intended for frontend navigation gating:

const { config } = useRegistryConfig();

// Hide navigation items based on features
{config?.features.mcp_servers && <NavItem>MCP Servers</NavItem>}
{config?.features.agents && <NavItem>A2A Agents</NavItem>}
{config?.features.skills && <NavItem>Skills</NavItem>}
{config?.features.federation && <NavItem>Federation</NavItem>}

Note: This frontend gating is not yet implemented. Currently all navigation items are visible regardless of mode.

Startup Logging

The registry logs its configuration at startup:

INFO: Registry Configuration:
INFO:   DEPLOYMENT_MODE: registry-only
INFO:   REGISTRY_MODE: skills-only
INFO:   Nginx updates: DISABLED

If an invalid combination is detected:

WARNING: ============================================================
WARNING: Invalid configuration detected!
WARNING: DEPLOYMENT_MODE=with-gateway is incompatible with REGISTRY_MODE=skills-only
WARNING: Auto-correcting to DEPLOYMENT_MODE=registry-only
WARNING: ============================================================

Nginx Behavior in Registry-Only Mode

When DEPLOYMENT_MODE=registry-only:

  1. Server Registration: Nginx configuration is NOT updated
  2. Server Deletion: Nginx configuration is NOT updated
  3. MCP Proxy Requests: Return 503 with JSON error:
{
  "error": "gateway_proxy_disabled",
  "message": "Gateway proxy is disabled in registry-only mode. Use proxy_pass_url from server metadata for direct connection."
}

The 503 response applies to all paths except:

  • /api/* - Registry API endpoints
  • /oauth2/* - Authentication endpoints
  • /keycloak/*, /realms/*, /resources/* - Keycloak paths
  • /v0.1/* - Anthropic-compatible API
  • /health - Health check
  • /static/*, /assets/*, /_next/* - Static assets
  • /validate - Token validation

CLI Testing

Use the registry management CLI to check configuration:

# Check current configuration
uv run python api/registry_management.py \
    --registry-url http://localhost \
    --token-file .token \
    config --json

# Output formatted for readability
uv run python api/registry_management.py \
    --registry-url http://localhost \
    --token-file .token \
    config

Related Documentation