Windsurf

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.

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

Prerequisites

Windsurf installed (windsurf.com)
CodeAlive account with API key (Sign up here)
Indexed repositories in your CodeAlive dashboard

Setup

Locate Config File

Windsurf reads MCP configuration from:

~/.codeium/windsurf/mcp_config.json

Create the file if it doesn’t exist.

Add CodeAlive Server

Remote HTTP (Recommended)
Docker (STDIO)

Add this to ~/.codeium/windsurf/mcp_config.json:

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

Windsurf uses serverUrl (not url). Using the wrong key will silently fail.

{
  "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 Windsurf

Close and reopen Windsurf to load the new MCP configuration.

Verify Integration

In Windsurf’s AI chat, try:

“What repositories are available in CodeAlive?”
“Search for authentication code in my codebase”

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

MCP server not connecting

Verify you’re using serverUrl (not url) in the config
Check that the config file is at ~/.codeium/windsurf/mcp_config.json
Ensure the type is streamable-http
Restart Windsurf completely

Authentication errors

Verify your API key is correct
Ensure the Authorization header includes Bearer prefix
Try regenerating your API key in the dashboard

For more solutions, see the Troubleshooting Guide.

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

Setup

Usage

Troubleshooting

Instruct Your Agent

​Overview

​Prerequisites

​Setup

​Usage

​Troubleshooting

​Related Resources

​Instruct Your Agent

Overview

Prerequisites

Setup

Usage

Troubleshooting

Related Resources

Instruct Your Agent