# How to Configure API Key Authentication for a Remote MCP Server

> Learn to configure API key authentication for your remote MCP server. Set http_remote_hosted to True, define your validation endpoint, and secure requests with X-Api-Key header validation.

- Repository: [Coplay/unity-mcp](https://github.com/CoplayDev/unity-mcp)
- Tags: how-to-guide
- Published: 2026-07-06

---

**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`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/core/config.py), set the `http_remote_hosted` attribute on the global `config` object:

```python
from Server.src.core.config import config

# Enable HTTP transport instead of STDIO

config.http_remote_hosted = True

```

When [`Server/src/main.py`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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

```python

# 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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/transport/unity_transport.py) (lines 31-35) processes standard HTTP requests
- **WebSocket Hub**: [`Server/src/transport/plugin_hub.py`](https://github.com/CoplayDev/unity-mcp/blob/main/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:

```json
{
  "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:

```python

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

```bash
python -m Server.src.main

```

### Method 2: Environment Variables

Alternatively, export variables before execution:

```bash
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:

```python
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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/main.py) (lines 621-627) via the `ApiKeyService` singleton
- **Transport enforcement** happens in [`Server/src/transport/unity_transport.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/transport/unity_transport.py) and [`Server/src/transport/plugin_hub.py`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/transport/unity_transport.py) (lines 31-35) and [`Server/src/transport/plugin_hub.py`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/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`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/transport/unity_transport.py) (lines 31-35) for regular API requests, and the WebSocket hub at [`Server/src/transport/plugin_hub.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/transport/plugin_hub.py) (lines 154-162) for persistent plugin connections. Both invoke `ApiKeyService.validate` before allowing requests to proceed to Unity.