How to Configure API Key Authentication for a Remote MCP Server

To configure API key authentication for a remote MCP server, enable remote-hosted mode by setting config.http_remote_hosted = True, define your external validation endpoint in the ServerConfig dataclass, and ensure the ApiKeyService singleton validates the X-Api-Key header on every incoming request.

When deploying the CoplayDev/unity-mcp server in remote-hosted HTTP mode, securing connections with API key authentication is mandatory. Unlike the local STDIO bridge, remote mode requires every client request to present a valid key verified against an external authentication service. This guide walks through the configuration files, service initialization, and transport layer enforcement mechanisms that make this possible.

Enable Remote-Hosted Mode

The server operates in two distinct transport modes: local STDIO and remote HTTP. To switch to remote-hosted mode, you must toggle the configuration flag before the server entry point initializes the transport layer.

In Server/src/core/config.py, set the http_remote_hosted attribute on the global config object:

from Server.src.core.config import config

# Enable HTTP transport instead of STDIO

config.http_remote_hosted = True

When Server/src/main.py executes, it reads this flag (lines 621-627) and initializes the HTTP transport stack rather than the standard input/output bridge.

Configure the Validation Endpoint

With remote mode enabled, the server requires details about where to validate incoming API keys. The ServerConfig dataclass in Server/src/core/config.py stores all authentication-related URLs and credentials.

Set the following attributes:

• api_key_validation_url: The HTTPS endpoint that receives POST requests containing {"api_key":"..."} and returns validation status
• api_key_login_url: Optional URL returned to clients in error messages, directing them where to obtain valid credentials
• api_key_service_token_header and api_key_service_token: Optional credentials the MCP server uses to authenticate itself to your validation service

# Validation endpoint that checks key validity

config.api_key_validation_url = "https://auth.example.com/validate"

# Optional: URL shown to users when authentication fails

config.api_key_login_url = "https://auth.example.com/login"

# Optional: Service-to-service authentication

config.api_key_service_token_header = "X-Service-Token"
config.api_key_service_token = "super-secret-service-token"

Initialize the API Key Service

During server startup, Server/src/main.py instantiates a singleton ApiKeyService using the global configuration values (lines 621-627). This service, implemented in Server/src/services/api_key_service.py, handles HTTP POST requests to your validation endpoint, implements response caching to reduce latency, and manages retry logic for transient failures.

The service remains active for the server lifetime, validating every incoming request against the cached results or fresh validation calls.

Transport Layer Enforcement

Authentication enforcement occurs at the transport layer before requests reach Unity logic. Both HTTP transport implementations extract the X-Api-Key header and delegate validation to the ApiKeyService:

• Unity Transport: Server/src/transport/unity_transport.py (lines 31-35) processes standard HTTP requests
• WebSocket Hub: Server/src/transport/plugin_hub.py (lines 154-162) handles WebSocket connections

If the header is missing, malformed, or the validation service returns a non-200 response, the transport immediately returns:

{
  "error": "Invalid API key"
}

Configuration Methods

You can configure authentication either programmatically or via environment variables.

Method 1: Python Configuration

Define settings in a setup script before launching the server:

# config_setup.py

from Server.src.core.config import config

config.http_remote_hosted = True
config.api_key_validation_url = "https://auth.example.com/validate"
config.api_key_login_url = "https://auth.example.com/login"

Then start the server:

python -m Server.src.main

Method 2: Environment Variables

Alternatively, export variables before execution:

export MCP_HTTP_REMOTE_HOSTED=1
export MCP_API_KEY_VALIDATION_URL="https://auth.example.com/validate"
export MCP_API_KEY_LOGIN_URL="https://auth.example.com/login"
export MCP_API_KEY_SERVICE_TOKEN_HEADER="X-Service-Token"
export MCP_API_KEY_SERVICE_TOKEN="super-secret-service-token"

python -m Server.src.main

Client Implementation

Clients must include the X-Api-Key header with every request:

import httpx

API_KEY = "my-client-key"
headers = {"X-Api-Key": API_KEY}

resp = httpx.post(
    "http://localhost:6500/mcp/tool/manage_scene",
    json={"action": "list"},
    headers=headers,
)
print(resp.json())

Summary

• Enable remote mode by setting config.http_remote_hosted = True in Server/src/core/config.py before server startup
• Define validation endpoint details including URL and optional service tokens in the global config object
• Service initialization occurs in Server/src/main.py (lines 621-627) via the ApiKeyService singleton
• Transport enforcement happens in Server/src/transport/unity_transport.py and Server/src/transport/plugin_hub.py, which reject requests lacking the X-Api-Key header
• Configuration flexibility allows settings via Python code or environment variables prefixed with MCP_

Frequently Asked Questions

What HTTP header name does the server expect for API keys?

The server requires the X-Api-Key header on every request. Both Server/src/transport/unity_transport.py (lines 31-35) and Server/src/transport/plugin_hub.py (lines 154-162) specifically look for this header name when extracting credentials from incoming connections.

How do I troubleshoot "Invalid API key" errors?

First verify that your client sends the X-Api-Key header exactly as specified. Next, check that config.api_key_validation_url points to a working endpoint that accepts POST requests with JSON payloads containing {"api_key":"..."}. Finally, review the ApiKeyService implementation in Server/src/services/api_key_service.py to ensure network connectivity exists between the MCP server and your authentication service.

Can I configure API key authentication without modifying Python source files?

Yes. Rather than editing Server/src/core/config.py, you can set environment variables such as MCP_HTTP_REMOTE_HOSTED, MCP_API_KEY_VALIDATION_URL, and MCP_API_KEY_SERVICE_TOKEN before launching Server/src/main.py. The server reads these values during initialization to configure the ApiKeyService singleton.

Which transport layers enforce the API key check?

Authentication enforcement occurs in two locations: the standard HTTP transport at Server/src/transport/unity_transport.py (lines 31-35) for regular API requests, and the WebSocket hub at Server/src/transport/plugin_hub.py (lines 154-162) for persistent plugin connections. Both invoke ApiKeyService.validate before allowing requests to proceed to Unity.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}