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

# Cursor

> Integrate CodeAlive with Cursor IDE for AI-powered development

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

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

<Info>
  **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](#codealive-vs-cursors-built-in-codebase-search) and the ready-made rule in [Project Rules](#project-rules-for-codealive).
</Info>

<Note>
  Working with 1C:Enterprise (BSL)? Also read [CodeAlive & 1С](/guides/1c-agents) — the term "metadata" needs explicit disambiguation in 1C projects.
</Note>

## Prerequisites

* [Cursor](https://cursor.com) installed (latest version recommended)
* CodeAlive account ([Sign up here](https://app.codealive.ai))
* Indexed repositories in your CodeAlive dashboard

## Connecting to CodeAlive

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

    <Info>In older Cursor builds this panel was named **Tools & Integrations**.</Info>
  </Step>

  <Step title="Add the CodeAlive server">
    Cursor opens `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global) for editing. Paste this configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "codealive": {
          "url": "https://mcp.codealive.ai/api"
        }
      }
    }
    ```

    Save the file.

    <Info>Cursor detects the transport from the `url` field — Streamable HTTP first, with automatic SSE fallback.</Info>
    <Info>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`.</Info>
  </Step>

  <Step title="Verify the connection">
    Back on **Tools & MCP**, authenticate when prompted. The `codealive` server should then show a green status dot.
  </Step>

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

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

```text theme={null}
cursor://anysphere.cursor-deeplink/mcp/install?name=codealive&config=BASE64_CONFIG
```

Generate `BASE64_CONFIG` from this JSON:

```json theme={null}
{
  "url": "https://mcp.codealive.ai/api"
}
```

For example, on macOS / Linux:

```bash theme={null}
echo -n '{"url":"https://mcp.codealive.ai/api"}' | base64
```

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

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

```markdown theme={null}
---
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.
```

<Info>
  See [Instructing Coding Agents](/guides/instructing-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](https://cursor.com/docs/context/rules).
</Info>

## Usage Patterns

<Tabs>
  <Tab title="Smart Completion">
    ```text theme={null}
    Cursor AI: "Complete this function based on our codebase patterns"

    // Cursor analyzes existing patterns via CodeAlive
    // and suggests completions matching your style
    ```
  </Tab>

  <Tab title="Intelligent Refactoring">
    ```text theme={null}
    You: "Refactor this service to match our other microservices"

    Cursor: [Searches for microservice patterns]
            [Suggests refactoring based on architecture]
    ```
  </Tab>

  <Tab title="Context-Aware Debugging">
    ```text theme={null}
    You: "Why is this API endpoint failing?"

    Cursor: [Traces through related code using CodeAlive]
            [Identifies potential issues across files]
    ```
  </Tab>
</Tabs>

## Advanced Features

### Multi-File Operations

Cursor can use CodeAlive to work across multiple files:

<AccordionGroup>
  <Accordion title="Find Dependencies">
    ```text theme={null}
    "Show me all files that import UserService"
    "Find all API endpoints that call this function"
    "List database migrations related to users"
    ```
  </Accordion>

  <Accordion title="Impact Analysis">
    ```text theme={null}
    "What will break if I change this interface?"
    "Find all tests affected by this change"
    "Show usage of this deprecated method"
    ```
  </Accordion>

  <Accordion title="Pattern Matching">
    ```text theme={null}
    "Find similar error handling patterns"
    "Show all authentication middleware"
    "Locate all database transactions"
    ```
  </Accordion>
</AccordionGroup>

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

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

```json theme={null}
{
  "mcpServers": {
    "codealive": {
      "url": "https://mcp.codealive.ai/api",
      "headers": {
        "Authorization": "Bearer ${CODEALIVE_API_KEY}"
      }
    }
  }
}
```

2. Each teammate exports their own key before launching Cursor:

```bash theme={null}
export CODEALIVE_API_KEY="their_api_key"
```

## Docker Alternative

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

```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"
      ]
    }
  }
}
```

## Productivity Tips

<CardGroup cols={2}>
  <Card title="Slash Commands" icon="keyboard">
    Save recurring CodeAlive prompts as slash commands in `.cursor/commands` for one-tap reuse.
  </Card>

  <Card title="Beyond Context Windows" icon="window">
    Use CodeAlive for codebases that exceed the model's context limit — semantic search retrieves only the relevant slice.
  </Card>

  <Card title="Scoped Rules" icon="folder-tree">
    Use `globs` in `.cursor/rules/*.mdc` to apply CodeAlive guidance only where it matters.
  </Card>

  <Card title="Team Standards" icon="users">
    Share `.cursor/rules/codealive.mdc` via git to keep the whole team on the same workflow.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="CodeAlive not responding">
    **Solutions:**

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

  <Accordion title="Incomplete code context">
    **Solutions:**

    1. Ensure your repositories are fully indexed in the CodeAlive dashboard
    2. Wait for indexing to complete
    3. Verify the API key has access to the relevant repositories
    4. Check repository filters
  </Accordion>

  <Accordion title="Slow responses">
    **Solutions:**

    1. Use more specific queries
    2. Limit search to specific repositories
    3. Check indexing status in dashboard
    4. Consider the Docker option for lower-latency local-network deployments
  </Accordion>
</AccordionGroup>

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

## Related Resources

* [Instructing Coding Agents](/guides/instructing-agents)
* [CodeAlive & 1С (1C:Enterprise specifics)](/guides/1c-agents)
* [MCP Overview](/integrations/mcp)
* [Self-Hosting Guide](/integrations/mcp/self-hosting)
* [API Reference](/api-reference/toolapi/list-visible-data-sources)
* [Cursor MCP Documentation](https://cursor.com/docs/context/mcp)
* [Cursor Rules Documentation](https://cursor.com/docs/context/rules)

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