The CodebaseAgent-MCP server enables token-efficient, asynchronous codebase analysis by delegating large repository exploration to a dedicated OpenAI-compatible LLM (local or cloud-based), returning only relevant findings to the primary coding assistant to reduce token consumption, context size, and latency.
Core tools:
List available libraries (codebase_list_libraries): Retrieve all configured local codebases/libraries available for analysis.
Start async file discovery (codebase_start_job_related_files_search): Kick off a background job to find files relevant to a specific entity or action. Best used before full analysis to narrow down relevant files.
Start async codebase analysis (codebase_start_job_analysis): Launch a background job for deep analysis of a single entity or action, returning detailed insights, recommendations, implementation guidance, and usage examples. Works best after file discovery.
Check job status (codebase_get_job_status): Poll the progress of any running job until it reaches a terminal state (success or failure). Recommended polling interval: ~50 seconds.
Retrieve job results (codebase_get_job_result): Fetch the final result, error details, or latest partial output for a completed or in-progress job.
Cancel a job (codebase_cancel_job): Request cancellation of any queued or actively running job.
Additional features:
Qdrant integration for RAG caching and semantic retrieval of code entities.
Automatic conversation history compression.
Sandboxed filesystem access restricted to configured library roots.
Support for pluggable external stdio MCP tools.
Installation of subagents/skills into coding agent harnesses (ClaudeCode, OpenCode, Codex).
CLI utilities for preparing Qdrant models and indexing dependency libraries.
Allows using any OpenAI-compatible LLM as the analysis backend for repository exploration and codebase analysis, including token-efficient code analysis, conversation compression, and optional caching.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@CodebaseAgent-MCP Analyze the main module for performance issues"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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.
Related MCP server: Workspace Qdrant MCP
Connect your local or low-cost cloud LLM to CodebaseAgent-MCP.
Connect CodebaseAgent-MCP as an MCP-server to your harness (ClaudeCode, Codex, OpenCode, etc.).
Start your development prompt with the phrase "Use skill libraries-analysis-skill." to reduce your costs.
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.
(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.
The benchmark was conducted using the OpenCode harness because it provides detailed statistics for both the main agent session and all subagent sessions.
The google/gemma-4-12b-qat model was used on both the OpenCode harness side and the CodebaseAgent-MCP harness side.
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.
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.
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)Token-efficient code and dependency analysis for repositories whose files are larger than the connected model's context window.
Automatic conversation-history compression
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 such as LM Studio, llama.cpp servers, vLLM-compatible endpoints, or compatible hosted APIs.
Works with cloud OpenAI-compatible servers.
Async background jobs with SQLite persistence of results.
Install
Configure
Connect to your coding agent
Use CodebaseAgent-MCP
Install uv:
https://docs.astral.sh/uv/getting-started/installation/
Initialize and create the CodebaseAgent-MCP configuration via uvx:
uvx --from codebase-agent-mcp cb-agent-initIt 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.
uvx --from codebase-agent-mcp@latest cb-agent-initThis will not affect your config.
Technical details and configuration recommendations for local LLMs: docs
Edit codebase_agent.config.json before starting the server.
Define OpenAI-compatible LLM (either local or cloud)
Field | Purpose |
| OpenAI-compatible endpoint. |
| API key sent to the endpoint. Use a placeholder such as |
| Model name exposed by the OpenAI-compatible server. |
| When |
| Reasoning effort value sent with the request. Use |
| Model context window limit in tokens. |
Local repositories, dependency sources, or documentation trees that the harness may analyze.
Field | Purpose |
| Public name used as |
| Enables or disables the library. Disabled libraries are not listed or analyzed. |
| Absolute path to the local directory. The path must exist when enabled. |
| Extra guidance for this codebase, such as preferred APIs, documentation folders, or project conventions. |
CodebaseAgent-MCP works as a client to Qdrant: either local or cloud.
qdrant_fastembed, and qdrant_cloud enable the RAG cache. By default, qdrant_fastembed client is installed. Their configuration can contain:
Field | Purpose |
| Embedding model name. Defaults to |
| Keyword arguments passed to |
Before the first use, and after every change to the
"configuration"."model_name"field in theqdrant_*plugin configuration, it is necessary to initialize (download) the model before the next use of the MCP server. The procedure is described below in the "Usage" -> "Qdrant (Optional)" section.
Configure your MCP client (ClaudeCode/Codex/OpenCode/Hermes/PiAgent/etc.) to run CodebaseAgent-MCP via uvx:
{
"mcpServers": {
"codebase-agent-mcp": {
"command": "uvx",
"args": [
"codebase-agent-mcp"
]
}
}
}Go to the root directory of your project and run:
uvx --from codebase-agent-mcp cb-agent-install-skills-to-current-dirAlternatively, you may clone the repository using git clone https://github.com/FI-Mihej/codebase-agent-mcp.git and proceed manually:
ClaudeCode: copy ./codebase_agent/data/integration_to/claude/.claude to root dir of your project.
Codex: copy ./codebase_agent/data/integration_to/codex/.agents, ./codebase_agent/data/integration_to/codex/.codex and ./codebase_agent/data/integration_to/codex/.codex/config.toml to root dir of your project.
OpenCode: copy ./codebase_agent/data/integration_to/opencode/.opencode to root dir of your project.
Cursor: copy ./codebase_agent/data/integration_to/cursor/.cursor to root dir of your project.
Antigravity: copy ./codebase_agent/data/integration_to/antigravity/.agents to root dir of your project. Antigravity lacks an agent concept, which means the work will be less token-efficient than when using other harnesses. Be sure to enable Implicit Caching to achieve significant savings.
Hermes Agent: copy ./codebase_agent/data/integration_to/hermes/skills to root dir of your project.
Pi Coding Agent: 1. install https://github.com/nicobailon/pi-subagents or similar solution; 2. copy ./codebase_agent/data/integration_to/pi_agent/.pi to root dir of your project.
Start your development prompt with the phrase "Use skill libraries-analysis-skill."
Example prompt: with__codebase_agent__skills.md
Before the first run of the CodebaseAgent-MCP with the qdrant_* plugin(s) enabled, and after every change to the "configuration"."model_name" field in the qdrant_* plugin configuration, always run:
uvx --from codebase-agent-mcp cb-agent-ensure-qdrant-modelsPerform indexing of dependency library codebases to add the key features of individual entities (files, classes, functions) to the RAG storage.
uvx --from codebase-agent-mcp cb-agent-index-dependency-librariesEmbedding prompt injections into repository code is becoming increasingly widespread. This ranges from repositories maintained by Meta (github.com/facebook/*), where they mainly interfere with coding agents but are otherwise harmless, to genuinely dangerous cases that can lead to credential leaks, Social Security number exposure, financial losses, and other security incidents.
A few simple yet still effective examples:
Prompt injection: github.com/facebook/docusaurus
Result against Claude Code: PR #12105
Post on X by a Meta core developer, where the author celebrates the remarkably high effectiveness of the prompt injections they embedded in AGENTS.md, code comments, and other locations throughout the repository.
Prompt injection: github.com/ghostty-org/ghostty
The same approach, with similar results.
Real-world prompt injections use millions of effective wording variations, with new ones being created constantly.
Using regular expressions or other primitive techniques to defend against them is ineffective.
Guardrail models. Even the best guardrail models achieve robustness of only around 85%. That means approximately one out of every six attacks succeeds. Is that an acceptable level of protection for a production system? See: Evaluating the Robustness of Large Language Model Safety Guardrails Against Adversarial Attacks, Bag of Tricks for Subverting Reasoning-based Safety Guardrails, etc.
Naive LLM-based detection. There is now a substantial body of research arguing that using an LLM to detect prompt injections by prompting the same (or a similar) LLM is fundamentally unreliable due to vulnerabilities in the detector itself and unacceptably high false positive and/or false negative rates for production use. See: How Not to Detect Prompt Injections with an LLM (2025), WAInjectBench: Benchmarking Prompt Injection Detections for Web Agents, Formalizing and Benchmarking Prompt Injection Attacks and Defenses, Optimization-based Prompt Injection Attack to LLM-as-a-Judge, etc.
After adding a new dependency library (that is, adding a new entry to the libraries field in the configuration file), it is recommended to sanitize the dependency library codebases by removing prompt injections from them.
A dedicated tool for this purpose will be released very soon. Stay tuned for updates.
It will be launched similarly to the following:
uvx --from codebase-agent-mcp cb-agent-sanitize-library-codebasesGithub repository is a curated public mirror of the project. Active development (including experimental code and private research notes) happens in a private repository; selected snapshots are published here periodically.
Support for the qdrant_fastembed_gpu plugin.
Internal optimizations and an expanded set of tools.
Integration of a content sanitization system for prompt injection protection.
A configuration field for LLM instructions on how to use connected MCP servers.
An internal sub-agent hierarchy for faster LLM operation.
Based on Cengal
text_file_read_and_refactor_mcp - Token-efficient Python stdio MCP server exposing safe text-file search, reading, and refactoring tools. Tools automatically resolve the file BOM and codepage.
InterProcessPyObjects - High-performance package delivers blazing-fast inter-process communication through shared memory, enabling Python objects to be shared across processes with exceptional efficiency.
cengal_app_dir_path_finder - A Python module offering a unified API for easy retrieval of OS-specific application directories, enhancing data management across Windows, Linux, and macOS
cengal_cpu_info - Extended, cached CPU info with consistent output format.
cengal_memory_barriers - Fast cross-platform memory barriers for Python.
Bensbach - decompiler from Unreal Engine 3 bytecode to a Lisp-like script and compiler back to Unreal Engine 3 bytecode. Made for a game modding purposes
Realistic-Damage-Model-mod-for-Long-War - Mod for both the original XCOM:EW and the mod Long War. Was made with a Bensbach, which was made with Cengal
Copyright © 2026 ButenkoMS. All rights reserved.
Licensed under the Apache License, Version 2.0.
Request cancellation of a queued or running analysis job.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Job id returned by either `codebase_start_job_related_files_search` or `codebase_start_job_analysis`. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It mentions cancellation but fails to disclose important behavioral aspects such as irreversibility, scope of effect, or error states (e.g., what happens if the job is already complete or not found).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no wasted words. It efficiently conveys the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a cancellation action and the presence of an output schema (not shown), the description might be minimally sufficient. However, it lacks details on error handling or state dependencies, leaving gaps for an agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter, and the description in the schema already explains the source of job_id. The tool description adds minimal value beyond stating 'queued or running', which is not critical for parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Request cancellation' and identifies the resource as 'a queued or running analysis job'. It distinguishes from siblings which are about getting results, status, or starting jobs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to cancel jobs) but does not explicitly state when not to use or mention alternatives. The context of siblings gives some guidance, but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the final result, error, or latest partial output for an analysis job. You must poll using codebase_get_job_status tool until success/failure. This tool internally waits up to 50s/request. Avoid assuming failure before terminal status. You are forbidden to finish response while polling is running.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Job id returned by either `codebase_start_job_related_files_search` or `codebase_start_job_analysis`. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses significant behavioral traits: internal wait up to 50s, dependency on prior status polling, and a rule against finalizing during polling. However, there is minor ambiguity: mentioning 'latest partial output' suggests it may be called before terminal status, while the instruction to poll until success/failure implies it should not be. This slight inconsistency prevents a perfect score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, each earning its place: purpose first, then crucial usage rules and warnings. It is well-structured, front-loaded, and free of fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with no annotations, the description covers the essential context: polling sequence, wait behavior, failure handling, and a hard rule about not finalizing responses. The minor ambiguity about partial output versus terminal polling keeps it from being fully complete, but it is otherwise thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, job_id, has 100% schema description coverage and is fully explained in the schema as the id returned by the start job tools. The description adds no extra semantics beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Return the final result, error, or latest partial output for an analysis job') that clearly distinguishes it from sibling tools like codebase_get_job_status (status) and codebase_start_job_* (starting jobs). It unambiguously states what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: poll codebase_get_job_status until success/failure, then use this tool. It warns about the 50s internal wait, cautions against assuming failure before terminal status, and forbids finishing the response while polling is running. This is a complete workflow context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get async analysis job status. Checks the progress of both the codebase_start_job_related_files_search and codebase_start_job_analysis jobs. You must poll using codebase_get_job_status tool until success/failure. This tool internally waits up to 50s/request. Avoid assuming failure before terminal status. You are forbidden to finish response while polling is running.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Job id returned by either `codebase_start_job_related_files_search` or `codebase_start_job_analysis`. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility. It discloses that the tool internally waits up to 50s per request, warns against premature failure assumptions, and asserts a strict rule about not finishing responses during polling. This goes well beyond a generic 'get status' description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a bold, clear purpose statement, followed by compact actionable instructions. Every sentence adds value—polling requirement, 50s wait, terminal status, and the prohibition on premature response—with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter status polling tool with an output schema, the description fully covers purpose, usage, and behavioral constraints. It explains the relationship to the sibling job-starting tools and defines the polling loop, making it complete for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the single parameter (job_id), including its source and type. The description does not add further parameter-specific detail, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get async analysis job status' and specifically names both job-starting tools (`codebase_start_job_related_files_search` and `codebase_start_job_analysis`), making the tool's purpose unambiguous and distinguishing it from siblings that start jobs or get results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage guidance is explicit: 'You must poll using `codebase_get_job_status` tool until `success`/`failure`' and 'Avoid assuming failure before terminal status.' It also forbids finishing responses while polling, clearly defining when to use the tool and how to handle non-terminal states.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the public names of local libraries/codebases available for analysis.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses a read operation, but lacks details on completeness, performance, or any limitations. Adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no extraneous information. It is appropriately sized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no annotations, clear output), the description is sufficient to inform an agent. No additional details are necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and full schema coverage, the description adds little beyond stating the return value. Baseline is 4, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Return' and the resource 'public names of local libraries/codebases'. It distinguishes from sibling tools that focus on job management, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing available libraries, but does not explicitly state when to use this tool versus alternatives. No guidance on prerequisites or context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start async codebase analysis. Analyze single entity/action only. Return detailed analysis, recommendations, implementation guidance, usage examples. Prefer codebase_start_job_related_files_search first. Provide all relevant context (files, paths, symbols, imports, etc.). One topic or one context per request → wait for the result → send the next request! Instead "Find X, Y, Z, etc." you MUST: "Find X.", wait result, "Find Y.", wait for result, etc!
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Focused, detailed request to analyze one entity/action. Include all relevant context (purpose, paths, symbols, imports, etc.). One topic or one context per request. Instead "Find X, Y, Z, etc." you MUST: "Find X.", wait result, "Find Y.", wait for result, etc! | |
| library_name | Yes | Public library name returned by list_libraries. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses async behavior and return content (analysis, recommendations, etc.), but lacks detail on error handling, permissions, or side effects. With no annotations, more behavioral context is expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bold emphasis, front-loading purpose. Some repetition of instructions between description and parameter schema, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 parameters, output schema, and siblings, description covers async nature, single-entity focus, sibling precedence, and usage pattern. Missing error/cancellation notes but still solid.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters; description adds value by reinforcing the query's required focus and one-topic rule. Adds meaningful guidance beyond schema basics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States 'Start async codebase analysis' with specific verbs and resource, and distinguishes from siblings by emphasizing single-entity analysis and preference for related_files_search. Clear and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly suggests using codebase_start_job_related_files_search first, and mandates one topic per request with wait-for-result pattern. Provides clear when-to-use and when-not-to.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0codebase_cancel_jobcodebase_get_job_resultcodebase_get_job_statuscodebase_list_librariescodebase_start_job_analysiscodebase_start_job_related_files_searchEach tool has a unique, clearly defined purpose: listing libraries, starting a related-file search, starting an analysis, checking status, fetching results, and cancelling. The two start_job tools are distinct (search vs analysis) and their descriptions explicitly differentiate them.
All tool names follow a consistent codebase_verb_noun pattern using snake_case. The start_job_* prefix is uniform, and get_job_status/get_job_result/cancel_job are intuitive and predictable.
With 6 tools, the count is well-scoped for a codebase analysis server. Each tool maps to a necessary step in the async job lifecycle, with no redundancy or bloat.
The core workflow (list libraries, start jobs, poll, retrieve, cancel) is fully covered. A minor gap is the lack of a way to list active or past jobs, which would help recover a lost job ID, but agents can work around this by storing IDs returned from start calls.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Driflyte MCP server which lets AI assistants query topic-specific knowledge from web and GitHub.
The CustomGPT.ai MCP server is a fully managed, RAG-powered endpoint that connects large language models with private knowledge bases and external data sources. It provides tools for retrieval-augmented generation queries (send_message), data ingestion (upload_file), and source listing, enabling AI agents to query private documents like PDFs with high accuracy and real-time citations.
An MCP server that gives your AI access to the source code and docs of all public github repos
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/FI-Mihej/codebase-agent-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
