Skip to main content

​
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 \
  -e CODEALIVE_API_KEY=YOUR_API_KEY \
  --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"
    environment:
      - CODEALIVE_API_KEY=${CODEALIVE_API_KEY}
    restart: unless-stopped
Run with: 
export CODEALIVE_API_KEY="your_api_key"
docker-compose up -d

​
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 .

# Set environment variable
export CODEALIVE_API_KEY="your_api_key"

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

​
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_API_KEY=YOUR_API_KEY \
  -e CODEALIVE_BASE_URL=https://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"
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

Check:
  • API key is correctly set
  • Port 8000 is not already in use
  • Docker daemon is running
View logs:
docker logs codealive-mcp
Check:
  • Server is running: docker ps or check Python process
  • Correct URL in your AI assistant configuration
  • Firewall allows connections to the port
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"
    }
  }
}
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