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

# Migrate to MCP v3

> Upgrade a CodeAlive MCP v1 or v2 integration to the eleven-tool MCP v3 contract

MCP v3 moves CodeAlive integrations onto the public Tool API v3 contract. It
adds repository orientation, bounded file reading, relationship traversal, and
metadata analytics while making tool names and arguments consistent across MCP
and the HTTP API.

This guide uses **v1** for the original CodeAlive MCP generation built around
`get_data_sources`, `codebase_search`, and `codebase_consultant`, and **v2** for
the later generation that also exposed canonical search, fetch, and
relationship tools.

<Info>
  The hosted MCP endpoint and existing CodeAlive API keys do not change. For most
  remote users, the upgrade is: refresh the MCP configuration, restart the
  client, and update any prompts or automation that call old tool names or
  arguments.
</Info>

## What changed

| Area                  | v1 / v2                                                                        | v3                                                                                                   |
| --------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| Tool set              | Three core tools in v1; search, fetch, and relationship tools added through v2 | Eleven canonical tools covering orientation, search, traversal, reading, analytics, and synthesis    |
| Legacy aliases        | `codebase_search`, `codebase_consultant`                                       | Removed from the MCP tool list                                                                       |
| Semantic-search input | `query`                                                                        | `question`                                                                                           |
| Data-source readiness | `alive_only`                                                                   | `ready_only`                                                                                         |
| Relationship profiles | camelCase values such as `callsOnly`                                           | snake\_case values such as `calls_only`                                                              |
| Chat state            | Optional `conversation_id`                                                     | Stateless; include all required context in each `question`                                           |
| Errors                | Tool-specific text and transport errors                                        | Repairable failures return actionable `<tool_error>` content and set the MCP result's `isError` flag |

## Migrate with your agent

Paste this prompt into the coding agent you want to migrate. It inventories
every CodeAlive integration available to the agent, upgrades each installed
method, preserves self-hosted addresses, and tests the migrated tools. Mintlify
code blocks include a copy button in the upper-right corner.

```text title="Agent migration prompt" theme={null}
Migrate every CodeAlive integration installed for this user or the current
project to the v3 Tool API. Do the work yourself with the shell, filesystem,
package manager, Docker, and UI tools available to you. Do not stop after
giving me instructions when you can perform the next step safely.

<safety>
- Never print, copy, or replace API keys, tokens, passwords, private
  certificates, or other secrets. Refer to existing credentials without
  exposing their values.
- Preserve unrelated agent configuration and create a backup before editing a
  configuration file.
- Never replace a self-hosted address with a CodeAlive cloud address.
- Do not install an integration method that was not already present. More than
  one method may be installed; update and verify every method you find.
- Do not claim success based only on files, versions, or tool discovery. Run
  the verification calls in <verification> through every updated integration.
</safety>

<inventory>
Before changing anything, inspect both user-level and project-level locations
and identify all of the following:

1. CodeAlive MCP configurations used by this agent and any other detected
   agents. Determine whether each one uses the hosted remote endpoint, a
   self-hosted remote endpoint, Docker, or a source checkout.
2. Every installed copy or symlink of the `codealive-context-engine` Agent
   Skill, including copies installed manually or through a skill/plugin
   manager.
3. The CodeAlive native Claude Desktop Extension (`codealive-mcp.mcpb`), if it
   is installed.

For each installation, record its owning client, scope, installed version or
source, installation path, and whether it uses CodeAlive cloud or self-hosted
CodeAlive. For self-hosted installations, record all non-secret addresses
before updating anything: the MCP endpoint, the CodeAlive deployment origin
used by skills or extensions, and any `CODEALIVE_BASE_URL` value. Redact query
strings, credentials, and authorization headers.

Show me the inventory, then continue with the migration without waiting for
confirmation unless a destructive production operation, elevated permission,
or maintenance-window approval is required.
</inventory>

<upgrade>
Update every installation found in <inventory>:

1. MCP configurations and servers
   - For CodeAlive cloud, use `https://mcp.codealive.ai/api/` and keep the
     existing credential reference.
   - For a standalone Docker or source-based MCP server, update it to the
     current v3 release using the existing deployment method. Preserve its
     self-hosted `CODEALIVE_BASE_URL`, MCP listen URL, CA trust settings,
     network settings, and credential references.
   - For the self-hosted CodeAlive deployment described by
     `selfhosted/UPGRADE-FROM-EARLY-APRIL-2026.md`, follow that runbook instead
     of applying the generic standalone-server procedure. Respect all of its
     preflight, backup, maintenance-window, migration, and rollback gates. Its
     embedded MCP endpoint after the application upgrade is
     `https://<DOMAIN>/mcp/api`.
   - Remove or disable stale v1/v2 duplicates only after the replacement has
     the same intended cloud or self-hosted destination.

2. Agent Skills
   - Update every installed `codealive-context-engine` copy with its existing
     skill/plugin manager. If it has no managed update path, reinstall it from
     `CodeAlive-AI/codealive-skills@codealive-context-engine` in the same scope.
   - An update may overwrite local URL changes. After every skill update,
     restore the recorded self-hosted deployment origin. Prefer setting
     `CODEALIVE_BASE_URL=https://<DOMAIN>` in the same non-secret agent or
     process configuration that launches the skill. The skill appends the Tool
     API path itself; do not set this value to the MCP endpoint
     `https://<DOMAIN>/mcp/api`.
   - If that agent cannot pass `CODEALIVE_BASE_URL`, patch the updated skill's
     default cloud origin to the recorded self-hosted deployment origin,
     report every patched file, and do not change any credential handling.

3. Claude Desktop Extension
   - If the native CodeAlive extension is installed, download and install this
     v3 bundle as its replacement:
     https://github.com/CodeAlive-AI/codealive-mcp/releases/download/v3.0.2/codealive-mcp.mcpb
   - Preserve the existing API-key reference and the recorded CodeAlive Base
     URL. For self-hosted CodeAlive, the extension's base URL is the deployment
     origin `https://<DOMAIN>`, not the embedded MCP endpoint.
   - Use Claude Desktop UI automation if available. If the extension installer
     requires the user to confirm a native dialog, prepare the downloaded file
     and ask for only that confirmation.

4. Search project instructions, prompts, automation, and programmatic MCP
   calls in scope for v1/v2 names and arguments. Apply the migration mappings
   on this page, including `codebase_search` to `semantic_search`,
   `codebase_consultant` to `chat`, semantic `query` to `question`,
   `alive_only` to `ready_only`, removal of `conversation_id`, and snake_case
   relationship profiles. Do not modify historical examples or vendored files
   unless they are active inputs.
</upgrade>

<verification>
Verify each updated MCP, Agent Skill, and Claude Desktop Extension path
independently. Do not use a working MCP installation as proof that a separate
skill or extension works.

For each path:

1. Call `get_data_sources` (or run the skill's equivalent data-source script)
   and select one ready data source from the actual response.
2. Run `semantic_search` against that data source with the v3 `question`
   argument and confirm it returns a successful, non-error response.
3. Take a concrete identifier or text fragment from the response and run
   `grep_search` against the same data source. Confirm it returns a successful,
   non-error response.
4. For MCP-based paths, confirm the client discovers the eleven canonical v3
   tools and does not expose `codebase_search` or `codebase_consultant`.

If there is no ready data source, report that verification is blocked and the
exact action needed; do not substitute a configuration check for these calls.
</verification>

<restart_gate>
Determine whether each updated client, extension, MCP process, container, or
agent must restart to reload its configuration or tool list. Restart it when
that is safe and does not terminate this migration session. Otherwise tell me
explicitly:

- exactly which application or process I must restart;
- why the restart is required;
- which verification steps remain pending afterward.

Never silently restart the agent that is running this conversation. Never
declare the migration complete until the required restart has happened and
the post-restart verification calls have passed. If this conversation cannot
survive the restart, give me a short continuation prompt that performs only
the remaining verification.
</restart_gate>

<final_report>
Report:

- every installation found and whether it was updated;
- the final non-secret cloud or self-hosted URL used by each installation;
- the result of `get_data_sources`, `semantic_search`, and `grep_search` for
  each path;
- files or settings changed;
- any required restart or remaining blocker.
</final_report>
```

## Before you upgrade

1. Locate the CodeAlive entry in your agent's MCP configuration.
2. Record whether it uses the hosted endpoint, Docker, or a source checkout.
3. Search project instructions and automation for the removed aliases and old
   argument names shown below.
4. Keep your existing API key. Do not paste it into source-controlled config.

<Warning>
  Do not keep an old and a new CodeAlive server entry enabled at the same time.
  Clients may discover duplicate tools and route calls to the stale server.
</Warning>

## Step 1: upgrade the server connection

<Tabs>
  <Tab title="Installer (recommended)">
    Run the installer again and let it update every detected agent:

    ```bash theme={null}
    npx @codealive/installer
    ```

    Review the detected clients, keep **MCP Server** selected, and restart each
    client after the installer finishes.
  </Tab>

  <Tab title="Hosted MCP">
    Keep the existing API key and make sure the server URL is exactly:

    ```text theme={null}
    https://mcp.codealive.ai/api/
    ```

    Compare your client configuration with its current setup page under
    [MCP integrations](/integrations/mcp). Save the configuration and fully
    restart the client so it discards the cached v1/v2 tool list.
  </Tab>

  <Tab title="Docker">
    Pull and recreate the container from the current image:

    ```bash theme={null}
    docker pull ghcr.io/codealive-ai/codealive-mcp:main
    ```

    If you use Compose, update the image to
    `ghcr.io/codealive-ai/codealive-mcp:main`, then run:

    ```bash theme={null}
    docker compose pull
    docker compose up -d
    ```

    Preserve `CODEALIVE_API_KEY`, `CODEALIVE_BASE_URL` for self-hosted CodeAlive,
    and any network allowlists. See [Self-hosting](/integrations/mcp/self-hosting)
    for the current container and HTTP configuration.
  </Tab>

  <Tab title="Source checkout">
    Update the checkout, recreate the locked environment, and restart the process:

    ```bash theme={null}
    git pull --ff-only
    uv sync --locked
    ```

    Follow the runtime and `uv` versions documented in the current
    [MCP repository](https://github.com/CodeAlive-AI/codealive-mcp). If your
    deployment pins a release tag, move the pin to the latest `v3.x` release
    instead of tracking `main`.
  </Tab>
</Tabs>

## Step 2: replace removed tool names

Update project rules, system prompts, saved workflows, and programmatic MCP
calls:

| Old tool                     | v3 replacement               | Required adjustment                                                      |
| ---------------------------- | ---------------------------- | ------------------------------------------------------------------------ |
| `codebase_search`            | `semantic_search`            | Rename `query` to `question`; remove `mode` and `description_detail`     |
| `codebase_consultant`        | `chat`                       | Remove `conversation_id`; include prior findings and scope in `question` |
| `semantic_search`            | `semantic_search`            | Rename `query` to `question`                                             |
| `grep_search`                | `grep_search`                | No required rename; `query` remains the exact text or regex              |
| `get_data_sources`           | `get_data_sources`           | Rename `alive_only` to `ready_only`                                      |
| `fetch_artifacts`            | `fetch_artifacts`            | No required argument changes                                             |
| `get_artifact_relationships` | `get_artifact_relationships` | Convert `profile` values to snake\_case                                  |

### Search call

```json title="Before (v1 / v2)" theme={null}
{
  "tool": "codebase_search",
  "arguments": {
    "query": "How does request authentication work?",
    "data_sources": ["backend"],
    "mode": "auto",
    "description_detail": "short"
  }
}
```

```json title="After (v3)" theme={null}
{
  "tool": "semantic_search",
  "arguments": {
    "question": "How does request authentication work?",
    "data_sources": ["backend"]
  }
}
```

### Chat call

```json title="Before (v1 / v2)" theme={null}
{
  "tool": "codebase_consultant",
  "arguments": {
    "question": "How does authentication work?",
    "data_sources": ["backend"],
    "conversation_id": "previous-session-id"
  }
}
```

```json title="After (v3)" theme={null}
{
  "tool": "chat",
  "arguments": {
    "question": "Explain authentication in backend. Prior findings: the request enters through AuthController and token validation is performed by AccessTokenValidator. Verify the complete flow and cite relevant artifacts.",
    "data_sources": ["backend"]
  }
}
```

<Note>
  `chat` is the slowest and most expensive MCP tool. For an agent that can run
  several tool calls, prefer `semantic_search` and `grep_search`, then read the
  returned identifiers with `fetch_artifacts` and inspect their relationships.
</Note>

### Relationship profile values

| v2 value          | v3 value           |
| ----------------- | ------------------ |
| `callsOnly`       | `calls_only`       |
| `inheritanceOnly` | `inheritance_only` |
| `allRelevant`     | `all_relevant`     |
| `referencesOnly`  | `references_only`  |

## Step 3: adopt the new tools

The existing calls can be migrated without using every new capability at once.
Add these tools to agent allowlists and orchestration code when ready:

| New v3 tool                 | Use it for                                          |
| --------------------------- | --------------------------------------------------- |
| `get_repository_ontology`   | High-level orientation for one repository           |
| `get_file_tree`             | A bounded repository or directory tree              |
| `read_file`                 | Exact-path reading with optional line bounds        |
| `get_artifact_query_schema` | Discovering the ArtifactQuery v1 schema             |
| `query_artifact_metadata`   | Read-only repository metrics and metadata analytics |

The complete v3 set is documented on the [MCP overview](/integrations/mcp) and
in the [Tool API Reference](/api-reference/toolapi/list-visible-data-sources).

## Step 4: update agent instructions

Old prompts often tell the agent to call one broad consultant tool. A v3 prompt
should make direct evidence gathering the default:

```markdown theme={null}
When researching indexed code, use CodeAlive tools in this order:

1. Call `get_data_sources` to resolve repository or workspace names.
2. Use `semantic_search` for behaviour and architecture questions.
3. Use `grep_search` for exact identifiers, strings, errors, and regexes.
4. Read relevant identifiers with `fetch_artifacts` and traverse callers,
   callees, inheritance, or references with `get_artifact_relationships`.
5. Use `chat` only when explicitly requested. Every chat call is stateless, so
   include all prior findings and scope in its `question`.
```

For production-ready routing rules, see
[Instructing Coding Agents](/guides/instructing-agents).

## Step 5: verify the migration

After restarting the client:

1. Open its MCP tools panel and confirm that CodeAlive exposes **eleven** tools.
2. Confirm `codebase_search` and `codebase_consultant` are absent.
3. Call `get_data_sources` with `{ "ready_only": false }`.
4. Call `semantic_search` with a full English `question` and one returned data
   source name.
5. If you automate relationship traversal, exercise at least one snake\_case
   profile such as `calls_only`.
6. Trigger one intentionally invalid development call and confirm the client
   surfaces a repairable `<tool_error>` instead of treating it as an empty
   successful result.

<Check>
  The migration is complete when the client discovers only the canonical v3
  tools and no prompt, rule, test fixture, or integration code references the
  removed aliases, `conversation_id`, `alive_only`, or camelCase relationship
  profiles.
</Check>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The client still shows old tools">
    Fully quit and restart the client; many MCP clients cache tool discovery for
    the process lifetime. Also check for a second CodeAlive entry that still points
    to an old local process or container.
  </Accordion>

  <Accordion title="semantic_search rejects query">
    MCP v3 renamed the semantic input to `question`. Keep `query` only for
    `grep_search` and for the optional relevance filter on `get_data_sources`.
  </Accordion>

  <Accordion title="Relationship traversal rejects the profile">
    Replace the v2 camelCase value with its v3 snake\_case equivalent from the table
    above.
  </Accordion>

  <Accordion title="A chat follow-up lost its context">
    This is expected in v3: `chat` is stateless. Put the relevant prior findings,
    identifiers, scope, and constraints into every new `question`, or keep the
    research loop in your own agent and use the direct tools instead.
  </Accordion>
</AccordionGroup>