CodebaseAgent-MCP

NOTE:

Based on my actual use of this subharness in my daily life (analyzing large volumes of data such as documents, sets of scientific papers, huge content saved from the government websites with poor filtering/search functionality, etc. - meaning it is far from just helping large LLMs retrieve information from large codebases) - this project is now smoothly evolving into a standalone general-purpose long-horizon agent subharness that can be connected to any CLI/GUI agent. This is for ease of use and to minimize the amount of my personal time spent writing and maintaining a high-quality custom CLI/GUI interface (rather than buggy or half-working, like many popular CLI/GUI agents written blindly by Claude/Codex).

CodebaseAgent-MCP is a token-efficient MCP server for AI coding agents that delegates large codebase analysis to a dedicated OpenAI-compatible LLM, reducing context size, latency, and token costs. Instead of forcing your primary coding assistant to repeatedly scan large codebases, it performs that work separately and returns only the information needed for the current task.

It can run against local models such as Gemma or Qwen, as well as inexpensive OpenAI-compatible cloud providers, reducing both latency and token consumption while keeping the primary assistant focused on reasoning and code generation.

Optional Qdrant integration can cache previous retrieval results today and is planned to evolve into semantic retrieval of code entities (files, classes and functions) from connected codebases.

QA

Why don't you just use LangChain?

Because I am intentionally focused on the OpenAI Chat Completions API, which is historically the most fully supported interface across third-party inference servers. Furthermore, LangChain cannot (and "not planned" to) retrieve or send, as part of the chat history, unofficial but de facto established custom fields for reasoning. Using reasoning during a chat process is a key necessity both because research shows it drastically improves the quality of LLM outputs in long-horizon chats and because it allows me to precisely manage the inference process from outside the inference server - for example, by stopping a looped generation process for reasoning and responses in models where you can only set the reasoning level but cannot disable it entirely.

Github repository

The GitHub repository is my public mirror of the project. As I usually do, I conduct active development (including experimental code and private research notes) in a private repository (part of my research monorepos with binary data that need to be versioned - these exceed GitHub's limits, and it is impractical to deal with workarounds for such limitations in experimental projects); selected snapshots are published here periodically.

Nevertheless, pull requests are welcome (not from LLMs).

Subharness features

• Designed specifically for managing small LLMs: it focuses on addressing their specific behavioral characteristics and weaknesses that prevent other harnesses from working with them effectively.
• Precise conversation-history compaction.
• Recursive subagent tree with configurable depth.
• LLM anti-stuck mechanism (prevents the model from falling into infinite self-repetition loops).
• Task completion control (prevents premature termination of work by small LLM)
• A tree of full-fledged subagents.
• Both STDIO and HTTP modes.
• Token-efficient code and dependency analysis for repositories whose files are larger than the connected model's context window.
• Optional RAG cache through one of the qdrant_* built-in plugins.
• Sandboxed filesystem access scoped to configured library roots.
• Pluggable external stdio MCP tools.
• Works with local OpenAI-compatible servers (LM Studio, llama.cpp, vLLM, Sglang, etc.), or compatible hosted APIs.
• Works with cloud OpenAI-compatible servers (OpenRouter, etc.).
• Async background jobs with SQLite persistence of results.

Why

Modern coding agents repeatedly spend thousands (sometimes millions) of tokens re-reading repositories, dependency sources, and documentation before they can start solving the actual task.

This becomes even more expensive when:

• the project is actively evolving;
• documentation is incomplete or outdated;
• source code must be inspected directly;
• each new agent session starts from an empty context.

CodebaseAgent-MCP delegates this exploration to a dedicated analysis model. The primary coding assistant receives only the relevant findings instead of repeatedly processing the entire codebase.

How it works

1. Connect your local or low-cost cloud LLM to CodebaseAgent-MCP.
2. Connect CodebaseAgent-MCP as an MCP-server to your harness (ClaudeCode, Codex, OpenCode, etc.).
3. Start your development prompt with the phrase "Use skill libraries-analysis-skill." to reduce your costs.

Benchmark

Task

task.md - write two small applications with a combined size of approximately 200 lines of code that use the Cengal library (inter-process communication, async multiprocessing app with TUI, async wxPython GUI).

In real-world development, the number of output tokens is also relatively small compared to the amount of project data that must be reread every session and kept in the context window, consuming input tokens. The scale of both the work and the associated costs is simply much larger.

Measurements

(VectorDB caching in CodebaseAgent-MCP was disabled to evaluate performance under the worst possible conditions.)

Tokens spent during the search and analysis stage of the Cengal codebase:

| Approach | All Input tok. | Input tok. | Cached Input tok. | Output tok. | | ---------------------- | -------------- | ---------- | ----------------- | ----------- | | without | 791930 | 684087 | 107843 | 5361 | | With CodebaseAgent-MCP | 416160 | 229003 | 187157 | 13755 |

Estimated costs based on the current token pricing of various models:

| Approach | Claude Haiku 4.5 | Claude Sonnet 5 (Sep 1, 2026) | Claude Opus 4.8 | Claude Fable 5 | GPT-5.5 | GPT-5.5-Pro * | | ---------------------- | ---------------- | ----------------------------- | --------------- | -------------- | -------- | ------------- | | without | 0.89 USD | 2.68 USD | 4.46 USD | 8.93 USD | 3.64 USD | 24.72 USD | | With CodebaseAgent-MCP | 0.37 USD | 1.12 USD | 1.87 USD | 3.74 USD | 1.65 USD | 14.96 USD | | Cost Reduction (×) | 2.4 | 2.39 | 2.39 | 2.39 | 2.2 * | 1.65 |

• GPT Pro models do not support cached tokens.
• I used a conservative (minimum) estimate for cached tokens. OpenAI dynamically accounts for cached tokens for GPT models (except Pro), meaning significantly more tokens are actually billed as cached. As a result, the real advantage of using CodebaseAgent-MCP is greater than "2.2×" because the proportion of cached tokens is higher when using CodebaseAgent-MCP than without it.

When VectorDB caching (qdrant_* plugins) is enabled in CodebaseAgent-MCP, the savings become even greater.

Harness

The benchmark was conducted using the OpenCode harness because it provides detailed statistics for both the main agent session and all subagent sessions.

LLM

The google/gemma-4-12b-qat model was used on both the OpenCode harness side and the CodebaseAgent-MCP harness side.

Prompts

• with__codebase_agent__agents.md
  • The MCP server for CodebaseAgent-MCP was the only one connected to OpenCode, with agents and skills installed in the project dir.
• without__codebase_agent__subagents.md
  • All MCP servers were subsequently disconnected (disabled) from OpenCode, and no agents or skills remain installed.
  • The phrase "Spawn subagents." is, of course, a significant advantage for plain OpenCode. I ended up using it out of necessity because, without it, clean OpenCode would consistently fall into an infinite loop: "Conduct research -> write one or two files until the context window is full -> delete part of the conversation history instead of summarizing it -> start over". At the same time, the CodebaseAgent-MCP server connected to OpenCode completes the task successfully even without any installed skills or agents, though it does so slightly less efficiently than with them.

Cached Input

Every provider implements caching differently, and some do not support it at all. I chose a conservative accounting method that produces the minimum possible number of cached tokens to avoid overstating the results. In particular, the actual number of cached tokens with OpenAI would be approximately 1.2-1.5× higher than my calculations because of OpenAI's dynamic caching algorithm. As a result, the advantage of using CodebaseAgent-MCP with GPT-5.5 would likely be comparable to, or even greater than, the savings observed with Anthropic models.

Architecture

ClaudeCode + Opus -> CodebaseAgent-MCP -> OpenAI-compatible LLM (either local or cloud)
                         |
                         +-> configured local codebases
                         +-> built-in tools and plugins
                         +-> optional Qdrant cache
                         +-> external MCP plugins (any MCP-servers of your choice)

How-To Start

1. Install
2. Configure
3. Connect to your coding agent
4. Use CodebaseAgent-MCP

Installation

1. Install uv: https://docs.astral.sh/uv/getting-started/installation/

2. Initialize and create the CodebaseAgent-MCP configuration via uvx:

uvx --from codebase-agent-mcp cb-agent-init

It will return the path to your codebase_agent.config.json configuration file.

Feel free to use uvx --from codebase-agent-mcp cb-agent-init at any time to find the location of your configuration file.

Update to latest version

uvx --from codebase-agent-mcp@latest cb-agent-init

This will not affect your config.

Configuration

Technical details and configuration recommendations for local LLMs: docs

Edit codebase_agent.config.json before starting the server.

Minimal config

Define OpenAI-compatible LLM (either local or cloud)

| Field | Purpose | | --- | --- | | base_url | OpenAI-compatible endpoint. /v1 is appended automatically when omitted. | | api_key | API key sent to the endpoint. Use a placeholder such as [EMPTY] for local servers that do not require a key. | | model | Model name exposed by the OpenAI-compatible server. | | reasoning_allowed | When false, the client sends provider additional hints that disable thinking/reasoning where supported. | | reasoning_effort | Reasoning effort value sent wit