Migrate to MCP v3

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.

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.

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.

Agent migration prompt

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

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

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.

Step 1: upgrade the server connection

Installer (recommended)
Hosted MCP
Docker
Source checkout

Run the installer again and let it update every detected agent:

npx @codealive/installer

Review the detected clients, keep MCP Server selected, and restart each client after the installer finishes.

Keep the existing API key and make sure the server URL is exactly:

https://mcp.codealive.ai/api/

Compare your client configuration with its current setup page under MCP integrations. Save the configuration and fully restart the client so it discards the cached v1/v2 tool list.

Pull and recreate the container from the current image:

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:

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 for the current container and HTTP configuration.

Update the checkout, recreate the locked environment, and restart the process:

git pull --ff-only
uv sync --locked

Follow the runtime and uv versions documented in the current MCP repository. If your deployment pins a release tag, move the pin to the latest v3.x release instead of tracking main.

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

Before (v1 / v2)

{
  "tool": "codebase_search",
  "arguments": {
    "query": "How does request authentication work?",
    "data_sources": ["backend"],
    "mode": "auto",
    "description_detail": "short"
  }
}

After (v3)

{
  "tool": "semantic_search",
  "arguments": {
    "question": "How does request authentication work?",
    "data_sources": ["backend"]
  }
}

Chat call

Before (v1 / v2)

{
  "tool": "codebase_consultant",
  "arguments": {
    "question": "How does authentication work?",
    "data_sources": ["backend"],
    "conversation_id": "previous-session-id"
  }
}

After (v3)

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

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.

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 and in the Tool API Reference.

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:

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.

Step 5: verify the migration

After restarting the client:

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

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.

Troubleshooting

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.

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.

Relationship traversal rejects the profile

Replace the v2 camelCase value with its v3 snake_case equivalent from the table above.

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.

Getting Started

Features

Model Context Protocol

Agent Skills & Plugins

Instructing Agents

What changed

Migrate with your agent

Before you upgrade

Step 1: upgrade the server connection

Step 2: replace removed tool names

Search call

Chat call

Relationship profile values

Step 3: adopt the new tools

Step 4: update agent instructions

Step 5: verify the migration

Troubleshooting

​What changed

​Migrate with your agent

​Before you upgrade

​Step 1: upgrade the server connection

​Step 2: replace removed tool names

​Search call

​Chat call

​Relationship profile values

​Step 3: adopt the new tools

​Step 4: update agent instructions

​Step 5: verify the migration

​Troubleshooting

What changed

Migrate with your agent

Before you upgrade

Step 1: upgrade the server connection

Step 2: replace removed tool names

Search call

Chat call

Relationship profile values

Step 3: adopt the new tools

Step 4: update agent instructions

Step 5: verify the migration

Troubleshooting