Claude Desktop

Overview

Integrate CodeAlive with Claude Desktop to enhance your AI assistant with deep understanding of your entire codebase. This integration uses the Model Context Protocol (MCP) to provide Claude Desktop with semantic search and code intelligence capabilities.

Quick install: Run npx @codealive/installer to automatically configure CodeAlive for this agent. See the Installation Guide for details.

Prerequisites

Claude Desktop installed
CodeAlive account with API key (Sign up here)
Indexed repositories in your CodeAlive dashboard

Installation Methods

Native Extension (Recommended)
Docker (STDIO) Fallback

This is the best fit for Claude Desktop when you authenticate with a bearer token. It uses Claude Desktop’s native extension installer, stores the API key securely, and supports self-hosted CodeAlive via a configurable base URL.

Build the Extension Bundle

From the codealive-mcp repository:

npm install -g @anthropic-ai/mcpb
mcpb pack

This produces a .mcpb bundle you can install into Claude Desktop.

Install in Claude Desktop

Open Settings → Extensions → Install Extension… and select the generated .mcpb file.

Configure CodeAlive

Fill in these settings in Claude Desktop:

CodeAlive API Key — your bearer token
CodeAlive Base URL — your deployment origin, for example https://codealive.yourcompany.com
Ignore TLS Errors — only for development or self-signed test environments

https://host is preferred. https://host/api is also accepted and normalized automatically.

This setup adds CodeAlive as a local MCP server in claude_desktop_config.json using Docker (STDIO). If you want to use Claude Desktop remote connectors instead, add them through Claude Desktop settings.

Locate Configuration File

Find your Claude Desktop configuration file:macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Create the file if it doesn’t exist.

Add CodeAlive Server

Add this Docker (STDIO) configuration:

{
  "mcpServers": {
    "codealive": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CODEALIVE_API_KEY=YOUR_API_KEY_HERE",
        "ghcr.io/codealive-ai/codealive-mcp:main"
      ]
    }
  }
}

Replace YOUR_API_KEY_HERE with your actual CodeAlive API key.

Restart Claude Desktop

Completely quit and restart Claude Desktop:

macOS: Cmd+Q then reopen
Windows: Alt+F4 then reopen

Verification

Test the integration by asking Claude:

"What CodeAlive repositories are available?"
"Search for authentication code in my codebase"
"Explain the main architecture of my project"

Usage Examples

Code Review
Debugging
Documentation

You: "Review the recent changes in the user service for security issues"

Claude: [Searches for user service code]
        [Analyzes security patterns]
        [Provides specific recommendations]

You: "Help me debug why the API is returning 500 errors"

Claude: [Searches for error handling code]
        [Traces through stack traces]
        [Identifies potential causes]

You: "Generate API documentation for the payment endpoints"

Claude: [Analyzes payment API code]
        [Extracts request/response schemas]
        [Creates comprehensive documentation]

Advanced Configuration

Multiple API Keys

Use separate servers for different teams or environments:

{
  "mcpServers": {
    "codealive-production": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CODEALIVE_API_KEY=PROD_API_KEY",
        "ghcr.io/codealive-ai/codealive-mcp:main"
      ]
    },
    "codealive-development": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CODEALIVE_API_KEY=DEV_API_KEY",
        "ghcr.io/codealive-ai/codealive-mcp:main"
      ]
    }
  }
}

Windows & WSL

Claude Desktop on Windows cannot connect to MCP servers running inside WSL directly. Use one of these approaches instead.

Docker Desktop (Recommended)
wsl.exe Proxy
Native Extension

If Docker Desktop is installed on Windows, the Docker STDIO configuration above works as-is — docker is in the Windows PATH.

If Docker is only available inside WSL, use wsl.exe as a bridge in claude_desktop_config.json:

{
  "mcpServers": {
    "codealive": {
      "command": "wsl.exe",
      "args": [
        "--", "docker", "run", "--rm", "-i",
        "-e", "CODEALIVE_API_KEY=YOUR_API_KEY_HERE",
        "ghcr.io/codealive-ai/codealive-mcp:main"
      ]
    }
  }
}

The .mcpb extension bundle (see Native Extension tab above) works on Windows without any WSL workarounds — it connects to the CodeAlive cloud API directly over HTTP.

Troubleshooting

Claude doesn't recognize CodeAlive commands

Solutions:

Verify JSON syntax in configuration file
Ensure Claude Desktop was fully restarted (Cmd+Q/Alt+F4)
Check API key is valid and active
Look for errors in Claude Desktop logs

No repositories found

Solutions:

Verify repositories are indexed in dashboard
Wait for indexing to complete (5-15 minutes)
Check API key has repository access
Test API key with curl command

Connection timeouts

Solutions:

Check network connectivity
Verify firewall allows outbound HTTPS
Try Docker deployment for local access
Check CodeAlive service status

Docker container issues

Solutions:

Ensure Docker is running
Check port 8000 is not in use
Verify environment variables are set
Review container logs for errors

For more solutions, see the Troubleshooting Guide.

Best Practices

Security

Store API keys securely, use environment variables

Performance

Use Docker for faster local responses

Organization

Use separate configs for different projects

Updates

Keep repositories indexed regularly

Instruct Your Agent

Connecting CodeAlive makes its tools available, but the agent may still default to its built-in search. For reliable results, add a short instruction in the agent’s native format telling it to prefer semantic_search and grep_search when exploring indexed code. See Instructing Coding Agents.

Getting Started

Features

Model Context Protocol

Agent Skills & Plugins

Instructing Agents

Overview

Prerequisites

Installation Methods

Verification

Usage Examples

Advanced Configuration

Multiple API Keys

Windows & WSL

Troubleshooting

Best Practices

Security

Performance

Organization

Updates

Instruct Your Agent

​Overview

​Prerequisites

​Installation Methods

​Verification

​Usage Examples

​Advanced Configuration

​Multiple API Keys

​Windows & WSL

​Troubleshooting

​Best Practices

Security

Performance

Organization

Updates

​Related Resources

​Instruct Your Agent

Overview

Prerequisites

Installation Methods

Verification

Usage Examples

Advanced Configuration

Multiple API Keys

Windows & WSL

Troubleshooting

Best Practices

Related Resources

Instruct Your Agent