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:

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: 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¶

Invalid Combination (Auto-Corrected)¶

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¶

• Configuration Reference - All environment variables
• AWS ECS Deployment - Production deployment guide
• Static Token Auth - API authentication without IdP