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

# Model Context Protocol (MCP)

> Connect CodeAlive to AI assistants via Model Context Protocol for deep codebase understanding

## Overview

Model Context Protocol (MCP) is an open standard developed by Anthropic that enables AI assistants to connect with external tools and data sources. MCP is now generally available across major development platforms including VS Code, JetBrains IDEs, and more. CodeAlive's MCP server provides your AI assistant with deep, contextual understanding of your entire codebase through semantic search and intelligent code analysis.

<Info>
  Already using an older CodeAlive MCP integration? Follow the
  [MCP v1/v2 → v3 migration guide](/integrations/mcp/migrate-to-v3) to update
  tool names, arguments, prompts, and deployment configuration.
</Info>

## Why Use CodeAlive MCP?

<CardGroup cols={2}>
  <Card title="Deep Context" icon="brain">
    AI understands relationships across your entire codebase, not just individual files
  </Card>

  <Card title="Semantic Search" icon="magnifying-glass">
    Find code by meaning and intent, not just keywords
  </Card>

  <Card title="Multi-Repository" icon="folder-tree">
    Work seamlessly across multiple repositories in one session
  </Card>

  <Card title="Real-Time Updates" icon="sync">
    Always work with the latest indexed version of your code
  </Card>
</CardGroup>

## Deployment Options

CodeAlive MCP can be deployed in three ways, depending on your needs:

### 1. Remote Service (Recommended)

* **URL**: `https://mcp.codealive.ai/api/`
* **Best for**: Quick setup, no infrastructure management
* **Requirements**: CodeAlive API key
* **Supported Clients**: All MCP-compatible AI assistants

### 2. Docker Container

* **Image**: `ghcr.io/codealive-ai/codealive-mcp:main`
* **Best for**: Enterprise environments, local development
* **Requirements**: Docker, CodeAlive API key
* **Benefits**: Network isolation, custom configuration

### 3. Self-Hosted Instance

* **Repository**: [CodeAlive MCP Server](https://github.com/CodeAlive-AI/codealive-mcp)
* **Best for**: Complete control, custom modifications
* **Requirements**: Python 3.11+, infrastructure management
* **Benefits**: Full customization, on-premise deployment

## Getting Started

<Info>
  Add at least one repository to CodeAlive before creating an API key. You do not need to wait for indexing to finish to create the key, but MCP queries become useful only after the repository is indexed.
</Info>

<Steps>
  <Step title="Add a repository">
    1. Sign up or log in at [app.codealive.ai](https://app.codealive.ai)
    2. Go to **Repositories** in your dashboard
    3. Click **Add Repository**
    4. Connect your GitHub/GitLab/Bitbucket account
    5. Select at least one repository to add
  </Step>

  <Step title="Create your API key">
    1. Navigate to **MCP & API**
    2. Click **"+ Create API Key"**
    3. Copy your key immediately (it won't be displayed again)
    4. Store your API key securely
  </Step>

  <Step title="Wait for indexing">
    CodeAlive starts indexing after the repository is added. Wait for initial indexing to complete before expecting useful chat or search results. Initial indexing typically takes 5-15 minutes.
  </Step>

  <Step title="Choose Your Integration">
    **Quick setup:** Run `npx @codealive/installer` to auto-configure CodeAlive for your agents. See the [Installation Guide](/installation) for details.

    Or select your AI assistant to see manual setup instructions:

    <CardGroup cols={3}>
      <Card title="Claude Code" icon="robot" href="/integrations/mcp/claude-code">
        Remote MCP with OAuth support
      </Card>

      <Card title="VS Code + GitHub Copilot" icon="code" href="/integrations/mcp/vscode">
        Native MCP support (GA)
      </Card>

      <Card title="Cursor" icon="code" href="/integrations/mcp/cursor">
        MCP with elicitation & resources
      </Card>

      <Card title="Windsurf" icon="wind" href="/integrations/mcp/windsurf">
        Streamable HTTP with serverUrl
      </Card>

      <Card title="Continue" icon="forward-fast" href="/integrations/mcp/continue">
        Full MCP feature support
      </Card>

      <Card title="Cline" icon="terminal" href="/integrations/mcp/cline">
        Auto-tool creation capabilities
      </Card>

      <Card title="Claude Desktop" icon="robot" href="/integrations/mcp/claude-desktop">
        Desktop app with MCP
      </Card>

      <Card title="Codex" icon="terminal" href="/integrations/mcp/codex">
        OpenAI Codex CLI with TOML config
      </Card>

      <Card title="Gemini CLI" icon="gem" href="/integrations/mcp/gemini-cli">
        One-command setup
      </Card>

      <Card title="Amazon Q" icon="aws" href="/integrations/mcp/amazon-q">
        CLI and IDE integration
      </Card>

      <Card title="OpenCode" icon="terminal" href="/integrations/mcp/opencode">
        Terminal AI with remote transport
      </Card>

      <Card title="SourceCraft" icon="code-branch" href="/integrations/mcp/sourcecraft">
        Code Assistant and CLI setup
      </Card>

      <Card title="Zed" icon="z" href="/integrations/mcp/zed">
        Native remote MCP support
      </Card>

      <Card title="ChatGPT" icon="message" href="/integrations/mcp/chatgpt">
        Custom GPTs with Actions
      </Card>

      <Card title="Other Agents" icon="puzzle-piece" href="/integrations/mcp/other-agents">
        Roo Code, KodaCode, GigaCode, and more
      </Card>
    </CardGroup>
  </Step>
</Steps>

## Available MCP Tools

CodeAlive exposes eleven MCP v3 tools. The default discovery pair is `semantic_search` and `grep_search`; `chat` is a slower stateless synthesis fallback that should be called only when explicitly requested.

Agent-repairable failures, such as an invalid path or ambiguous data source,
return actionable `<tool_error>` text and set the MCP result's native
`isError` flag. Authentication, quota, network, and server failures are also
surfaced as tool errors rather than empty results.

### `get_data_sources`

Lists all indexed repositories and workspaces available for querying. Pass the optional `query` argument — a natural-language description of the task, such as "add OAuth to checkout" — to get only the data sources relevant to it, each with a `relevanceReason` explaining the match. Recommended whenever the agent knows what the user is trying to accomplish; omit `query` to list everything.

**Use cases:**

* Scope the source list to the current task with `query`
* Verify repository access
* Check indexing status
* List available codebases

### `semantic_search`

Canonical semantic search across indexed artifacts. Find code by meaning and intent, not just keywords.

**Use cases:**

* Find implementation patterns
* Locate specific functionality
* Discover related code
* Trace data flows

### `grep_search`

Canonical exact text or regex search with line-level previews.

**Use cases:**

* Find exact strings, identifiers, or log messages
* Run regex lookups across indexed repositories
* Confirm literal matches before fetching full source

### `chat`

Canonical synthesized codebase Q\&A tool.

Use `chat` only when explicitly requested and when you need a synthesized answer instead of direct evidence gathering. It can take substantially longer than retrieval. Tool API v3 chat is stateless: include prior findings, artifact identifiers, assumptions, scope, and constraints in every `question`. If your agent supports subagents and you need the highest reliability or depth, prefer a multi-step agent workflow that combines ontology, `semantic_search`, `grep_search`, `fetch_artifacts`, `read_file`, relationship inspection, metadata queries, and local file reads.

**Use cases:**

* Architecture explanations after search
* Synthesized flow walkthroughs
* One-shot answers with all required context included in the question

### `get_repository_ontology`

Get repository-level orientation for exactly one selected repository.

### `get_file_tree`

Inspect a bounded file tree for exactly one selected repository.

### `read_file`

Read a repository-relative file path, optionally bounded by line range.

### `fetch_artifacts`

Retrieve full source code content for specific artifacts found via search. Use this to get the actual code after reviewing search descriptions.

**Use cases:**

* Get full content for external repo search results
* Inspect specific functions or classes in detail
* Follow the search → review → fetch workflow

**Workflow:** Call `semantic_search` or `grep_search` first, review the descriptions or line previews and identifiers in the results, then call `fetch_artifacts` with the identifiers you want to inspect (max 50 per request). For repositories in your working directory, use local file reads instead.

**Optional `data_source` (disambiguation):** Each search result carries a `dataSource` `id` and `name`. When an identifier exists in more than one data source, pass that `name` or `id` as the optional `data_source` argument to scope the fetch to one source.

**Missing identifiers:** If some requested identifiers cannot be resolved (or are outside your access scope), the response is not silently truncated — they are listed in a `<not_found count="N">` block naming each concrete identifier, followed by a hint to re-check those ids and retry the problematic ones. Surface them to the user rather than omitting the requested artifact.

### `get_artifact_relationships`

Expand one artifact's call graph, inheritance hierarchy, or reference relationships after you already have its identifier.

**Use cases:**

* Trace outgoing and incoming calls for one function
* Explore class inheritance chains
* Inspect reference-heavy symbols without fetching whole files

**Optional `data_source` (disambiguation):** Same as `fetch_artifacts` — pass a data source `name` or `id` (from a search result's `dataSource`) to resolve an identifier that exists in more than one data source.

<Note>
  **Handling the ambiguous-identifier 409.** If you call `fetch_artifacts` or `get_artifact_relationships` with an identifier that exists in more than one data source and you do **not** pass `data_source`, the backend returns a `409` and the tool surfaces the list of candidate data sources (by name and id). Each candidate **will** resolve, so the sequence is: call without `data_source` → read the 409 candidates → retry with one candidate's `name`/`id` → if that data source isn't the one you want, retry with the next. Do not invent a result.

  **Scoped request found nothing.** If you *did* pass `data_source` but the call comes back empty (`fetch_artifacts` returns no content, `get_artifact_relationships` returns `found: false`), the tool emits a hint: the identifier likely belongs to a **different** data source, or the `data_source` value is wrong. Retry with a different candidate's `name`/`id`, or omit `data_source` to get the `409` candidate list — don't conclude the artifact doesn't exist.
</Note>

### `get_artifact_query_schema`

Inspect supported ArtifactQuery entities, fields, operators, and examples before writing metadata queries.

### `query_artifact_metadata`

Run read-only metadata analytics across selected repositories. Use this for aggregate questions such as file counts, languages, complexity, relationship counts, and metadata filtering.

## Common Use Cases

<Tabs>
  <Tab title="Code Understanding">
    ```
    You: "Explain how user authentication works in our system"

    AI: [Searches for authentication code across repositories]
        [Maps out the complete auth flow]
        [Explains with actual code references]
    ```
  </Tab>

  <Tab title="Bug Investigation">
    ```
    You: "Debug why payments are failing intermittently"

    AI: [Searches for payment processing code]
        [Analyzes error handling and retry logic]
        [Identifies potential race conditions]
    ```
  </Tab>

  <Tab title="Code Generation">
    ```
    You: "Create a new API endpoint following our patterns"

    AI: [Analyzes existing API endpoints]
        [Identifies conventions and patterns]
        [Generates code matching your style]
    ```
  </Tab>

  <Tab title="Architecture Analysis">
    ```
    You: "What would be impacted if we change this database schema?"

    AI: [Searches for all references to the schema]
        [Maps dependencies across services]
        [Lists required migrations and updates]
    ```
  </Tab>
</Tabs>

## Security & Privacy

<Info>
  CodeAlive MCP follows security best practices:

  * All connections are encrypted with TLS
  * API keys are never logged or stored in plain text
  * Repository access is controlled at the API key level
  * Self-hosted options available for sensitive codebases
</Info>

## Best Practices

<CardGroup cols={2}>
  <Card title="Keep Repos Updated" icon="sync">
    Regularly sync repositories in your dashboard for accurate context
  </Card>

  <Card title="Use Specific Queries" icon="target">
    Be precise with technical terms for better search results
  </Card>

  <Card title="Organize by Project" icon="folder">
    Use separate API keys for different projects or environments
  </Card>

  <Card title="Monitor Usage" icon="chart-bar">
    Track API usage in your dashboard to optimize queries
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection Issues">
    **Common causes:**

    * Invalid or expired API key
    * Network connectivity problems
    * Incorrect MCP server URL

    **Solutions:**

    1. Regenerate API key in dashboard
    2. Check network/firewall settings
    3. Verify URL is `https://mcp.codealive.ai/api/`
  </Accordion>

  <Accordion title="No Repositories Found">
    **Common causes:**

    * Repositories not indexed
    * API key lacks permissions
    * Indexing still in progress

    **Solutions:**

    1. Check indexing status in dashboard
    2. Wait 5-15 minutes for initial indexing
    3. Verify API key has repository access
  </Accordion>

  <Accordion title="Slow Response Times">
    **Common causes:**

    * Large codebase searches
    * Broad/vague queries
    * Network latency

    **Solutions:**

    1. Use more specific search queries
    2. Limit search to specific repositories
    3. Consider Docker or self-hosted deployment
  </Accordion>
</AccordionGroup>

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Choose Your Client" icon="desktop" href="/integrations#mcp-integrations">
    Set up CodeAlive with your preferred AI assistant
  </Card>

  <Card title="Self-Hosting Guide" icon="server" href="/integrations/mcp/self-hosting">
    Deploy CodeAlive MCP on your infrastructure
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/toolapi/list-visible-data-sources">
    Explore the full CodeAlive API
  </Card>

  <Card title="GitHub Repository" icon="github" href="https://github.com/CodeAlive-AI/codealive-mcp">
    View source code and contribute
  </Card>
</CardGroup>