Cursor

Overview

Connect CodeAlive with Cursor IDE to enhance your AI-powered development experience. CodeAlive provides Cursor with deep contextual understanding of your entire codebase through the Model Context Protocol (MCP).

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

Cursor ships its own codebase_search and will prefer it by default. Connecting the MCP server is not enough — add a project rule so Cursor’s agent reaches for CodeAlive first. See CodeAlive vs Cursor’s built-in codebase search and the ready-made rule in Project Rules.

Working with 1C:Enterprise (BSL)? Also read CodeAlive & 1С — the term “metadata” needs explicit disambiguation in 1C projects.

Prerequisites

Cursor installed (latest version recommended)
CodeAlive account (Sign up here)
Indexed repositories in your CodeAlive dashboard

Connecting to CodeAlive

Open MCP settings

Open Cursor Settings:

macOS: Cmd+, or menu Cursor → Settings
Windows/Linux: Ctrl+, or File → Preferences → Settings

Then go to Tools & MCP in the left panel and click New MCP Server.

In older Cursor builds this panel was named Tools & Integrations.

Add the CodeAlive server

Cursor opens .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global) for editing. Paste this configuration:

{
  "mcpServers": {
    "codealive": {
      "url": "https://mcp.codealive.ai/api"
    }
  }
}

Save the file.

Cursor detects the transport from the url field — Streamable HTTP first, with automatic SSE fallback.

Cursor supports OAuth for remote Streamable HTTP servers. Follow the browser sign-in prompt; in Cursor Agent you can start it explicitly with cursor-agent mcp login codealive.

Verify the connection

Back on Tools & MCP, authenticate when prompted. The codealive server should then show a green status dot.

Try it in chat

Open Cursor’s chat panel and try:

“What repositories are available in CodeAlive?”
“Search for authentication logic in my codebase”
“Explain the architecture of my project”

One-Click Install Link

Cursor supports a deeplink that installs an MCP server in one click. Encode the CodeAlive config as base64 JSON and open this URL:

cursor://anysphere.cursor-deeplink/mcp/install?name=codealive&config=BASE64_CONFIG

Generate BASE64_CONFIG from this JSON:

{
  "url": "https://mcp.codealive.ai/api"
}

For example, on macOS / Linux:

echo -n '{"url":"https://mcp.codealive.ai/api"}' | base64

Only follow MCP deeplinks from trusted sources — clicking installs and configures a server without further confirmation.

CodeAlive vs Cursor’s built-in codebase search

Cursor’s agent has a native codebase_search tool backed by a local index of the open workspace. It cannot be disabled in the default Agent mode (tool selection is only available in Custom Modes, and the built-in search has known quirks there), and without instructions the planner will use it for every exploration question — your connected CodeAlive server never gets called. The two tools are not equivalent:

	Cursor `codebase_search`	CodeAlive `semantic_search`
Scope	The workspace you have open	Every indexed repository and workspace, including ones not checked out
Index	Local, per-machine	Server-side, kept in sync with the default branch
Cross-repo questions	No	Yes — one query across services
Code graph follow-up	No	`get_artifact_relationships`, `fetch_artifacts`

Since you cannot remove the built-in tool, the working approach is a precedence rule that names it explicitly. Vague phrasing (“prefer CodeAlive for search”) reliably loses to the planner’s default; naming codebase_search as the thing to avoid wins. That is what the rule below does.

Project Rules for CodeAlive

Project rules teach Cursor’s agent how to use CodeAlive. The legacy .cursorrules file is deprecated — use .cursor/rules/*.mdc (MDC format) instead. Cursor rules have four activation modes, controlled by the .mdc frontmatter:

Mode	Frontmatter	When the rule loads
Always	`alwaysApply: true`	Every chat and agent run
Auto Attached	`globs` set	When matching files are in context
Agent Requested	`description` set, `alwaysApply: false`	The agent decides, based on the description
Manual	none of the above	Only when you `@`-mention the rule

For a tool-precedence rule use Always — it must be active before the planner picks its first search tool, so an on-demand mode is too late. Keep it short for that same reason: always-on rules are injected into every request. Create .cursor/rules/codealive.mdc in your project:

---
description: CodeAlive is the primary code search and context engine
alwaysApply: true
---

# CodeAlive context engine

CodeAlive MCP tools search server-side indexes of all our repositories —
cross-repo, always in sync with the default branch.

## Search precedence (important)
- For exploration questions — "how does X work", "where is Y implemented",
  "what calls Z" — use CodeAlive `semantic_search` FIRST. Do NOT call the
  built-in `codebase_search` or plain grep for these questions unless
  CodeAlive has returned nothing useful twice.
- Phrase `semantic_search` as a full English sentence, never bare keywords.
  Keep exact identifiers verbatim.
- For exact symbol names, string literals, error messages, config keys, and
  acronyms use CodeAlive `grep_search` with the literal text (not a question).
- When a result returns an artifact identifier (`repo::path::symbol`), read it
  with `fetch_artifacts`; map callers/callees with `get_artifact_relationships`.
- Built-in tools remain fine for files currently being edited in this
  workspace; CodeAlive covers indexed history and repos not checked out here.

## Working with results
- Search for existing implementations before writing new code; match the
  patterns CodeAlive surfaces.
- When reviewing or refactoring, use `get_artifact_relationships`
  (`references_only`) to find all affected call sites across repositories.

See Instructing Coding Agents for the general patterns behind this rule (imperative + trigger, naming the built-in tool, sequencing) and a universal AGENTS.md variant that also covers teammates on other agents — Cursor’s CLI reads repo-root AGENTS.md too. Cursor rules reference: cursor.com/docs/context/rules.

Usage Patterns

Smart Completion
Intelligent Refactoring
Context-Aware Debugging

Cursor AI: "Complete this function based on our codebase patterns"

// Cursor analyzes existing patterns via CodeAlive
// and suggests completions matching your style

You: "Refactor this service to match our other microservices"

Cursor: [Searches for microservice patterns]
        [Suggests refactoring based on architecture]

You: "Why is this API endpoint failing?"

Cursor: [Traces through related code using CodeAlive]
        [Identifies potential issues across files]

Advanced Features

Multi-File Operations

Cursor can use CodeAlive to work across multiple files:

Find Dependencies

"Show me all files that import UserService"
"Find all API endpoints that call this function"
"List database migrations related to users"

Impact Analysis

"What will break if I change this interface?"
"Find all tests affected by this change"
"Show usage of this deprecated method"

Pattern Matching

"Find similar error handling patterns"
"Show all authentication middleware"
"Locate all database transactions"

Project vs Global Configuration

Cursor reads MCP servers from two locations:

Project-level: .cursor/mcp.json at the workspace root — commit this so the whole team gets the server.
Global: ~/.cursor/mcp.json — applies to every project on your machine.

If both files define a server with the same name, the project-level entry wins.

Team Collaboration

Share the project-level config without exposing API keys:

Commit .cursor/mcp.json referencing an environment variable:

{
  "mcpServers": {
    "codealive": {
      "url": "https://mcp.codealive.ai/api",
      "headers": {
        "Authorization": "Bearer ${CODEALIVE_API_KEY}"
      }
    }
  }
}

Each teammate exports their own key before launching Cursor:

export CODEALIVE_API_KEY="their_api_key"

Docker Alternative

Run the CodeAlive MCP server locally with Docker (stdio transport):

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

Productivity Tips

Slash Commands

Save recurring CodeAlive prompts as slash commands in .cursor/commands for one-tap reuse.

Beyond Context Windows

Use CodeAlive for codebases that exceed the model’s context limit — semantic search retrieves only the relevant slice.

Scoped Rules

Use globs in .cursor/rules/*.mdc to apply CodeAlive guidance only where it matters.

Team Standards

Share .cursor/rules/codealive.mdc via git to keep the whole team on the same workflow.

Troubleshooting

CodeAlive not responding

Solutions:

Check the server status indicator in Settings → Tools & MCP (green = healthy, red = failed)
Verify your API key is correct and active
Reload Cursor: Cmd/Ctrl+Shift+P → "Developer: Reload Window"
Check network connectivity to https://mcp.codealive.ai/api

Incomplete code context

Solutions:

Ensure your repositories are fully indexed in the CodeAlive dashboard
Wait for indexing to complete
Verify the API key has access to the relevant repositories
Check repository filters

Slow responses

Solutions:

Use more specific queries
Limit search to specific repositories
Check indexing status in dashboard
Consider the Docker option for lower-latency local-network deployments

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

Connecting to CodeAlive

One-Click Install Link

CodeAlive vs Cursor’s built-in codebase search

Project Rules for CodeAlive

Usage Patterns

Advanced Features

Multi-File Operations

Project vs Global Configuration

Team Collaboration

Docker Alternative

Productivity Tips

Slash Commands

Beyond Context Windows

Scoped Rules

Team Standards

Troubleshooting

Instruct Your Agent

​Overview

​Prerequisites

​Connecting to CodeAlive

​One-Click Install Link

​CodeAlive vs Cursor’s built-in codebase search

​Project Rules for CodeAlive

​Usage Patterns

​Advanced Features

​Multi-File Operations

​Project vs Global Configuration

​Team Collaboration

​Docker Alternative

​Productivity Tips

Slash Commands

Beyond Context Windows

Scoped Rules

Team Standards

​Troubleshooting

​Related Resources

​Instruct Your Agent

Overview

Prerequisites

Connecting to CodeAlive

One-Click Install Link

CodeAlive vs Cursor’s built-in codebase search

Project Rules for CodeAlive

Usage Patterns

Advanced Features

Multi-File Operations

Project vs Global Configuration

Team Collaboration

Docker Alternative

Productivity Tips

Troubleshooting

Related Resources

Instruct Your Agent