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

# Claude Desktop

> Connect CodeAlive with Claude Desktop application

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

<Tip>
  **Quick install:** Run `npx @codealive/installer` to automatically configure CodeAlive for this agent.
  See the [Installation Guide](/installation) for details.
</Tip>

## Prerequisites

* [Claude Desktop](https://claude.ai/download) installed
* CodeAlive account with API key ([Sign up here](https://app.codealive.ai))
* Indexed repositories in your CodeAlive dashboard

## Installation Methods

<Tabs>
  <Tab title="Native Extension (Recommended)">
    <Info>
      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.
    </Info>

    <Steps>
      <Step title="Build the Extension Bundle">
        From the `codealive-mcp` repository:

        ```bash theme={null}
        npm install -g @anthropic-ai/mcpb
        mcpb pack
        ```

        This produces a `.mcpb` bundle you can install into Claude Desktop.
      </Step>

      <Step title="Install in Claude Desktop">
        Open **Settings → Extensions → Install Extension...** and select the generated `.mcpb` file.
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Docker (STDIO) Fallback">
    <Info>
      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.
    </Info>

    <Steps>
      <Step title="Locate Configuration File">
        Find your Claude Desktop configuration file:

        **macOS**:

        ```bash theme={null}
        ~/Library/Application Support/Claude/claude_desktop_config.json
        ```

        **Windows**:

        ```bash theme={null}
        %APPDATA%\Claude\claude_desktop_config.json
        ```

        Create the file if it doesn't exist.
      </Step>

      <Step title="Add CodeAlive Server">
        Add this Docker (STDIO) configuration:

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

      <Step title="Restart Claude Desktop">
        Completely quit and restart Claude Desktop:

        * **macOS**: Cmd+Q then reopen
        * **Windows**: Alt+F4 then reopen
      </Step>
    </Steps>
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="Code Review">
    ```
    You: "Review the recent changes in the user service for security issues"

    Claude: [Searches for user service code]
            [Analyzes security patterns]
            [Provides specific recommendations]
    ```
  </Tab>

  <Tab title="Debugging">
    ```
    You: "Help me debug why the API is returning 500 errors"

    Claude: [Searches for error handling code]
            [Traces through stack traces]
            [Identifies potential causes]
    ```
  </Tab>

  <Tab title="Documentation">
    ```
    You: "Generate API documentation for the payment endpoints"

    Claude: [Analyzes payment API code]
            [Extracts request/response schemas]
            [Creates comprehensive documentation]
    ```
  </Tab>
</Tabs>

## Advanced Configuration

### Multiple API Keys

Use separate servers for different teams or environments:

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

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

<Tabs>
  <Tab title="Docker Desktop (Recommended)">
    If Docker Desktop is installed on Windows, the Docker STDIO configuration above works as-is — `docker` is in the Windows PATH.
  </Tab>

  <Tab title="wsl.exe Proxy">
    If Docker is only available inside WSL, use `wsl.exe` as a bridge in `claude_desktop_config.json`:

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

  <Tab title="Native Extension">
    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.
  </Tab>
</Tabs>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Claude doesn't recognize CodeAlive commands">
    **Solutions:**

    1. Verify JSON syntax in configuration file
    2. Ensure Claude Desktop was fully restarted (Cmd+Q/Alt+F4)
    3. Check API key is valid and active
    4. Look for errors in Claude Desktop logs
  </Accordion>

  <Accordion title="No repositories found">
    **Solutions:**

    1. Verify repositories are indexed in dashboard
    2. Wait for indexing to complete (5-15 minutes)
    3. Check API key has repository access
    4. Test API key with curl command
  </Accordion>

  <Accordion title="Connection timeouts">
    **Solutions:**

    1. Check network connectivity
    2. Verify firewall allows outbound HTTPS
    3. Try Docker deployment for local access
    4. Check CodeAlive service status
  </Accordion>

  <Accordion title="Docker container issues">
    **Solutions:**

    1. Ensure Docker is running
    2. Check port 8000 is not in use
    3. Verify environment variables are set
    4. Review container logs for errors
  </Accordion>
</AccordionGroup>

<Tip>
  For more solutions, see the [Troubleshooting Guide](/troubleshooting).
</Tip>

## Best Practices

<CardGroup cols={2}>
  <Card title="Security" icon="lock">
    Store API keys securely, use environment variables
  </Card>

  <Card title="Performance" icon="gauge">
    Use Docker for faster local responses
  </Card>

  <Card title="Organization" icon="folder">
    Use separate configs for different projects
  </Card>

  <Card title="Updates" icon="sync">
    Keep repositories indexed regularly
  </Card>
</CardGroup>

## Related Resources

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

## 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](https://docs.codealive.ai/guides/instructing-agents).