> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codealive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-Hosting Guide

> Deploy CodeAlive MCP server on your own infrastructure

## 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](https://app.codealive.ai)
* Docker (for container deployment) or Python 3.11+ (for source deployment)

## Docker Deployment

The easiest way to self-host CodeAlive MCP:

```bash theme={null}
# 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`:

```yaml theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
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

```json theme={null}
{
  "mcpServers": {
    "codealive": {
      "type": "http",
      "url": "http://localhost:8000/api"
    }
  }
}
```

### For Custom Port

```json theme={null}
{
  "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

```bash theme={null}
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:

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="Container won't start">
    Check:

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

    View logs:

    ```bash theme={null}
    docker logs codealive-mcp
    ```
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Authentication failures">
    Check:

    * API key is valid and active
    * Environment variable is set correctly
    * For self-hosted backend, verify base URL is correct
  </Accordion>
</AccordionGroup>

## WSL2 Networking

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

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

```ini theme={null}
[wsl2]
networkingMode=mirrored
```

Then restart WSL:

```bash theme={null}
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:

```bash theme={null}
hostname -I
```

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

```json theme={null}
{
  "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.

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

## Security Notes

<Warning>
  * 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
</Warning>

## Related Resources

* [MCP Overview](/integrations/mcp)
* [GitHub Repository](https://github.com/CodeAlive-AI/codealive-mcp)
* [API Reference](/api-reference/toolapi/list-visible-data-sources)