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

# Windsurf

> Connect CodeAlive with Windsurf AI coding assistant

## Overview

Connect CodeAlive with Windsurf (by Codeium) to enhance your AI coding assistant with deep contextual understanding of your entire codebase. Windsurf uses a unique MCP configuration with `serverUrl` instead of `url`.

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

## Prerequisites

* Windsurf installed ([windsurf.com](https://windsurf.com))
* CodeAlive account with API key ([Sign up here](https://app.codealive.ai))
* Indexed repositories in your CodeAlive dashboard

## Setup

<Steps>
  <Step title="Locate Config File">
    Windsurf reads MCP configuration from:

    ```
    ~/.codeium/windsurf/mcp_config.json
    ```

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

  <Step title="Add CodeAlive Server">
    <Tabs>
      <Tab title="Remote HTTP (Recommended)">
        Add this to `~/.codeium/windsurf/mcp_config.json`:

        ```json theme={null}
        {
          "mcpServers": {
            "codealive": {
              "type": "streamable-http",
              "serverUrl": "https://mcp.codealive.ai/api",
              "headers": {
                "Authorization": "Bearer YOUR_API_KEY_HERE"
              }
            }
          }
        }
        ```

        <Warning>
          Windsurf uses `serverUrl` (not `url`). Using the wrong key will silently fail.
        </Warning>
      </Tab>

      <Tab title="Docker (STDIO)">
        ```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"
              ]
            }
          }
        }
        ```
      </Tab>
    </Tabs>

    Replace `YOUR_API_KEY_HERE` with your actual CodeAlive API key.
  </Step>

  <Step title="Restart Windsurf">
    Close and reopen Windsurf to load the new MCP configuration.
  </Step>

  <Step title="Verify Integration">
    In Windsurf's AI chat, try:

    * "What repositories are available in CodeAlive?"
    * "Search for authentication code in my codebase"
  </Step>
</Steps>

## Usage

Once connected, Windsurf's AI assistant can:

* **Search your codebase** semantically across all indexed repositories
* **Answer architecture questions** with full project context
* **Find patterns and implementations** across multiple services

```
"Find all API endpoints in the user service"
"Explain how the payment flow works"
"Show me error handling patterns"
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="MCP server not connecting">
    1. Verify you're using `serverUrl` (not `url`) in the config
    2. Check that the config file is at `~/.codeium/windsurf/mcp_config.json`
    3. Ensure the `type` is `streamable-http`
    4. Restart Windsurf completely
  </Accordion>

  <Accordion title="Authentication errors">
    1. Verify your API key is correct
    2. Ensure the `Authorization` header includes `Bearer ` prefix
    3. Try regenerating your API key in the [dashboard](https://app.codealive.ai)
  </Accordion>
</AccordionGroup>

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

## Related Resources

* [MCP Overview](/integrations/mcp)
* [Installation Guide](/installation)
* [Self-Hosting Guide](/integrations/mcp/self-hosting)
* [Agent Skills](/integrations/skills)

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