Self-Hosting Guide

Overview

Self-host the CodeAlive MCP server for complete control over your deployment. The MCP server can be deployed using Docker or from source code.

Prerequisites

CodeAlive API key from app.codealive.ai
Docker (for container deployment) or Python 3.11+ (for source deployment)

Docker Deployment

The easiest way to self-host CodeAlive MCP:

# Pull the latest image
docker pull ghcr.io/codealive-ai/codealive-mcp:main

# Run the container
docker run -d \
  -p 8000:8000 \
  --name codealive-mcp \
  --restart unless-stopped \
  ghcr.io/codealive-ai/codealive-mcp:main

Docker Compose

Create docker-compose.yml:

version: '3.8'

services:
  codealive-mcp:
    image: ghcr.io/codealive-ai/codealive-mcp:main
    container_name: codealive-mcp
    ports:
      - "8000:8000"
    restart: unless-stopped

Run with:

docker-compose up -d

Clients authenticate each HTTP request with Authorization: Bearer YOUR_API_KEY; do not put one shared API key in the MCP server environment.

Source Code Deployment

Deploy from the GitHub repository:

# Clone the repository
git clone https://github.com/CodeAlive-AI/codealive-mcp.git
cd codealive-mcp

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

# Run the server
python src/codealive_mcp_server.py --transport http --host 0.0.0.0 --port 8000

HTTP Host and Origin protection

Loopback hosts (localhost, 127.0.0.1, ::1) are accepted by default. If clients reach the server through another hostname, add that exact host:

export CODEALIVE_MCP_ALLOWED_HOSTS="mcp.codealive.yourcompany.com"
# Only for browser JavaScript callers; normal MCP clients do not send Origin.
export CODEALIVE_MCP_ALLOWED_ORIGINS="https://mcp.codealive.yourcompany.com"
python src/codealive_mcp_server.py --transport http --host 0.0.0.0 --port 8000

You can instead repeat --allowed-host and --allowed-origin on the command line. Avoid wildcard allowlists on public deployments.

OAuth 2.1 rollout

Remote HTTP deployments can enable browser authorization without removing legacy API-key support. OAuth mode publishes MCP Protected Resource Metadata and exchanges each accepted MCP token for a separate short-lived Tool API token; it never forwards the incoming bearer token.

export CODEALIVE_MCP_OAUTH_ENABLED=true
export CODEALIVE_OAUTH_ISSUER="https://auth.your-codealive-instance.com/"
export CODEALIVE_MCP_RESOURCE="https://mcp.your-codealive-instance.com/api"
export CODEALIVE_TOOL_API_RESOURCE="urn:codealive:tool-api"
export CODEALIVE_OAUTH_INTERNAL_CLIENT_ID="codealive-mcp"
export CODEALIVE_OAUTH_INTERNAL_CLIENT_SECRET="use-a-secret-store"

The issuer, resources, internal client ID, and secret must exactly match the CodeAlive Web.Server McpOAuth settings. The internal secret is mandatory and the MCP process fails closed at startup if it is absent. Persist the Web.Server Data Protection key ring and OpenIddict certificates across restarts and replicas. Roll out the Web.Server and MCP feature flags together; neither half-enabled state is a valid steady state. Rotate the internal credential with a new versioned client ID instead of changing the secret under the existing ID. First deploy Web.Server with the new pair as InternalClientId/InternalClientSecret and the old pair as PreviousInternalClientId/PreviousInternalClientSecret. Then roll MCP replicas to the new pair and remove the previous pair after rollout verification. This overlap prevents old and new replicas from invalidating one another during a rolling deployment. OAuth and API-key credential routing is explicit. A token that fails OAuth validation is not retried as an API key, and an invalid API key is not retried as OAuth.

Custom Port

To run on a different port:

python src/codealive_mcp_server.py --transport http --host 0.0.0.0 --port 8080

Connecting to Self-Hosted Instance

Once your server is running, configure your AI assistant to use the local URL:

For Docker

{
  "mcpServers": {
    "codealive": {
      "type": "http",
      "url": "http://localhost:8000/api"
    }
  }
}

For Custom Port

{
  "mcpServers": {
    "codealive": {
      "type": "http",
      "url": "http://localhost:8080/api"
    }
  }
}

For Self-Hosted CodeAlive Backend

If you’re running a self-hosted CodeAlive instance (not just the MCP server), configure the base URL:

Docker

docker run -d \
  -p 8000:8000 \
  -e CODEALIVE_BASE_URL=https://your-codealive-instance.com \
  -e CODEALIVE_MCP_ALLOWED_HOSTS=mcp.your-codealive-instance.com \
  --name codealive-mcp \
  ghcr.io/codealive-ai/codealive-mcp:main

Source Code

Set additional environment variable:

export CODEALIVE_BASE_URL="https://your-codealive-instance.com"
export CODEALIVE_MCP_ALLOWED_HOSTS="mcp.your-codealive-instance.com"
python src/codealive_mcp_server.py --transport http --host 0.0.0.0 --port 8000

Use the deployment origin as the base URL. https://host is preferred. https://host/api is also accepted and normalized automatically by the latest MCP server and Claude Desktop extension.

Basic Troubleshooting

Container won't start

Check:

API key is correctly set
Port 8000 is not already in use
Docker daemon is running

View logs:

docker logs codealive-mcp

Connection refused

Check:

Server is running: docker ps or check Python process
Correct URL in your AI assistant configuration
Firewall allows connections to the port

Authentication failures

Check:

API key is valid and active
Environment variable is set correctly
For self-hosted backend, verify base URL is correct

WSL2 Networking

This section applies when the MCP server runs inside WSL2 and you connect from Windows-side clients (Claude Desktop, Cursor, VS Code, etc.).

WSL2 runs in a Hyper-V virtual machine with its own network. By default, localhost inside WSL2 is not the same as localhost on Windows. HTTP MCP servers listening on 127.0.0.1 inside WSL2 won’t be reachable from Windows clients. Fix 1: Enable mirrored networking (Windows 11 22H2+) Add to %USERPROFILE%\.wslconfig:

[wsl2]
networkingMode=mirrored

Then restart WSL:

wsl --shutdown

After this, localhost is shared between Windows and WSL2 — http://localhost:8000/api works from both sides. Fix 2: Use WSL2 VM IP Run inside WSL:

hostname -I

Use the returned IP in your client config instead of localhost:

{
  "mcpServers": {
    "codealive": {
      "type": "http",
      "url": "http://172.x.x.x:8000/api"
    }
  }
}

Also add that exact WSL address to CODEALIVE_MCP_ALLOWED_HOSTS; otherwise the HTTP request guard correctly rejects the non-loopback Host header.

The WSL2 VM IP can change after reboot. Mirrored networking is the more stable solution.

Security Notes

Never expose the MCP server directly to the internet
Keep your API keys secure
Use HTTPS in production environments
Consider using a reverse proxy for additional security

Getting Started

Features

Model Context Protocol

Agent Skills & Plugins

Instructing Agents

Self-Hosting Guide

Overview

Prerequisites

Docker Deployment

Docker Compose

Source Code Deployment

HTTP Host and Origin protection

OAuth 2.1 rollout

Custom Port

Connecting to Self-Hosted Instance

For Docker

For Custom Port

For Self-Hosted CodeAlive Backend

Docker

Source Code

Basic Troubleshooting

WSL2 Networking

Security Notes

​Overview

​Prerequisites

​Docker Deployment

​Docker Compose

​Source Code Deployment

​HTTP Host and Origin protection

​OAuth 2.1 rollout

​Custom Port

​Connecting to Self-Hosted Instance

​For Docker

​For Custom Port

​For Self-Hosted CodeAlive Backend

​Docker

​Source Code

​Basic Troubleshooting

​WSL2 Networking

​Security Notes

​Related Resources

Overview

Prerequisites

Docker Deployment

Docker Compose

Source Code Deployment

HTTP Host and Origin protection

OAuth 2.1 rollout

Custom Port

Connecting to Self-Hosted Instance

For Docker

For Custom Port

For Self-Hosted CodeAlive Backend

Docker

Source Code

Basic Troubleshooting

WSL2 Networking

Security Notes

Related Resources