How CodeAlive MCP evolved: from three tools to a research interface

The first working version of CodeAlive MCP landed on April 27, 2025. It was one Python file with three tools: get_data_sources, search_code, and chat_completions.

It worked, but the rough edges showed quickly. A single search could pull too much code into context. Responses spent tokens on formatting, and errors sometimes looked like successful tool results.

We changed the interface a piece at a time. The recurring rule was simple: keep search small, then return source and recovery guidance when the agent needs them.

2025: from a local adapter to remote MCP

The original search_code accepted natural language or code patterns and could include full file contents. chat_completions kept conversation state through conversation_id. Responses were made for people to read: introductory prose, indented JSON, labels, and usage notes.

In June we added Docker publishing. In July we moved to FastMCP 2, added HTTP transport with Bearer authentication, and announced the remote endpoint at https://mcp.codealive.io/api/. The implementation had existed since April; the public remote endpoint came later.

By autumn, the tools had become codebase_search and codebase_consultant. Search and chat also started accepting repository or workspace names instead of requiring opaque IDs. That made the output of get_data_sources much easier for a model to reuse.

Search formatting changed from prose and nested data to compact XML. The response kept the fields an agent needed for the next step: path, identifier, line range, kind, and a short description. The rest was dropped.

March 2026: search, then fetch

v0.5 added fetch_artifacts and removed the option to put full source directly into search results.

The flow became two-step:

1. Search returned small records for triage.
2. fetch_artifacts loaded source for the identifiers the agent chose.

This saved context and clarified how search results should be used. A generated description pointed to the evidence. The agent still had to fetch the source, or read the local file, before drawing conclusions.

fetch_artifacts used XML around the raw source so artifact boundaries stayed clear. Search could remain small even when the repository was not.

April 2026: one search tool became two

In April we added get_artifact_relationships, then split codebase_search into:

• semantic_search for concepts and behaviour when the exact name is unknown;
• grep_search for identifiers, literals, filenames, and regular expressions.

We also introduced the shorter chat name. The new tools reached production on April 8 and 9; the formal v2.0.0 tag followed on April 14.

Formatting became mixed on purpose. Search, data sources, and relationships moved to compact JSON, while fetch_artifacts kept XML around source. Soon after, FastMCP began returning search results as native structured data instead of a JSON string. Different results had different jobs, so forcing them into one format was not useful.

Error handling changed at the same time. Earlier versions returned strings such as Error: .... V2 raised native ToolError results with isError: true, so clients could tell failure from data. Empty searches suggested a better next call. Validation errors included the failing field and, when available, a request ID.

July 2026: MCP became a thin Tool API client

CodeAlive MCP 3.0 moved onto the same Tool API used by our other agent integrations. Each MCP tool now calls POST /api/tools/{name} with snake_case arguments and requests output_format: "agentic".

The server exposes 11 read-only tools:

• get_data_sources
• semantic_search and grep_search
• get_repository_ontology, get_file_tree, and read_file
• fetch_artifacts and get_artifact_relationships
• get_artifact_query_schema and query_artifact_metadata
• chat

The deprecated codebase_search and codebase_consultant aliases are gone. chat is stateless too: the caller passes relevant findings and constraints with each question instead of relying on conversation_id.

V3 also moved rendering into the backend. Every Tool API operation defines a structured obj and an agent-facing rendered form. MCP forwards rendered instead of maintaining its own formatters. Search currently uses compact XML, ontology uses Markdown, several retrieval tools use concise JSON, and chat returns plain text.

Repairable argument errors carry code, message, retry, and try, plus a rendered <tool_error> block. Authentication, quota, transport, and unexpected server failures remain HTTP errors.

The basic workflow has not changed. The agent finds a data source, searches it, fetches the relevant code, and asks for synthesis only when it needs it. V3 makes each of those calls narrower and keeps the payload smaller.

You can connect CodeAlive MCP using the integration guide or call the same operations through the Tool API.