Agent Context MCP
MCP server that provides deep agent context to your codebases!
Ask AI about Agent Context MCP
Powered by Claude · Grounded in docs
I know everything about Agent Context MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
agent-context
agent-context is a Rust-native MCP server that gives coding agents indexed code search across one or more local repositories.
[!IMPORTANT] This project is heavily inspired by claude-context. The core idea comes directly from that project: give coding agents an indexed code-search surface instead of making them repeatedly rediscover a codebase through shell search.
agent-contexttakes that approach and focuses it on a Rust-native local server, a shared HTTP MCP facade, multi-codebase search, and lower steady-state resource usage.
Overview
agent-context makes your agents smarter and faster. It helps them find the right code paths earlier, make more accurate changes in large codebases, move through tasks with fewer dead ends, and reduce token usage along the way.
How This Differs From MemPalace
MemPalace is a persistent memory system for agents. It is designed around long-term recall: conversations, mined knowledge, knowledge graphs, and agent diaries.
agent-context is narrower. It is a code-search system for coding agents:
- MemPalace helps an agent remember.
agent-contexthelps an agent navigate and retrieve the right code.
They are complementary more than competitive. If you want long-term agent memory, MemPalace is solving that problem. If you want more accurate semantic, lexical, and symbol search over real codebases, that is what agent-context is built for.
Features
agent-context is easiest to understand as a set of agent-facing capabilities:
- Semantic search for natural-language queries like
find the GraphQL schema builder. - Symbol search for exact definitions like
build_schema,KeyStore, orSessionManager. - Exact text search for literal strings inside a known repo, file, or bounded subtree when an agent needs precise confirmation instead of another ranked search.
- Edit-target preparation that returns live-file exact content, bounded edit windows, and unique patch anchors immediately before editing.
- File outlines so an agent can inspect structure without scanning entire files.
- Hybrid ranking so exact identifiers, paths, and semantic matches work in one search flow.
- Multi-repo scopes so one MCP server can search a named workspace instead of a single repo.
- Shared local MCP endpoint so Codex, Claude, Copilot, and other MCP clients can use the same index.
- Higher search accuracy in large codebases where agents often miss the existing implementation path, fail to find the right symbol or file, and start inventing parallel solutions that should not exist.
- Fewer tokens used per task because agents can retrieve the right files, symbols, and snippets earlier instead of spending turns probing, re-searching, and reading the wrong parts of the tree.
- Lower steady-state resource usage than heavier multi-process setups, while still keeping semantic, lexical, and symbol search available.
- Explicit local control over indexing, refreshes, providers, and service lifecycle.
The storage and indexing details matter, but they are implementation details. The product surface is simple: agents get a better way to search code.
That accuracy point matters. In larger repositories, the failure mode is usually not that an agent finds nothing. It is that the agent finds one plausible path, misses the real one, and then starts editing or building around an incomplete mental model of the codebase. Better semantic, lexical, and symbol search reduces that drift and makes it much more likely that the agent works on the code that already exists instead of creating a second, parallel path.
Language Support
agent-context does not support every language equally. Today, the practical support tiers are:
- Strong support: Rust, TypeScript, TSX, JavaScript, JSX, Python, Go, Java
- Supported with more conservative symbol extraction: C, C++, C#, Kotlin, PHP, Ruby, Swift, Scala
- Content-only support: Markdown
What that means in practice:
- All listed languages are indexed for code search and lexical retrieval.
- Strong-support languages are the ones with the highest confidence for symbol search and outlines.
- The conservative tier is still searchable, but symbol extraction is more best-effort and intentionally guarded to avoid poisoning refreshes on ambiguous syntax or generated code.
- Markdown is useful for semantic and lexical retrieval, but it is not presented as a symbol language.
How It Works
High-level architecture
flowchart LR
A["Codex / Claude / Copilot"] --> B
subgraph Server["agent-context process"]
direction TB
B["HTTP MCP facade"]
C["Hybrid search layer"]
B --> C
end
subgraph Indexes["Search indexes"]
direction TB
D["semantic search"]
E["lexical search"]
F["symbol database"]
end
subgraph Ingest["Indexing path"]
direction LR
H["Local repositories"] --> G["Indexer"]
end
C --> Indexes
G --> Indexes
Search request flow
flowchart TD
A["Agent calls search_code"] --> B["Query planner"]
B --> C["Semantic retrieval"]
B --> D["Lexical retrieval"]
B --> E["Symbol-aware boosts"]
C --> F["Result fusion"]
D --> F
E --> F
F --> G["Snippet + metadata assembly"]
G --> H["MCP response"]
Quick Start
This project assumes an agent can help with setup. The install path below is designed to be followed directly by an agent or a human.
Prerequisites
- macOS
- Docker Desktop or another local Docker runtime
- Homebrew
- one embedding provider:
- Voyage
- OpenAI
- Ollama
1. Install the tap and binary
brew install jeremymefford/agent-context-mcp/agent-context
agent-context --help
2. Start Milvus
docker compose -f docker/milvus-compose.yml up -d
3. Create a starter config
agent-context init --provider voyage --repo /absolute/path/to/repo
The canonical config path for the Homebrew install is:
~/Library/Application Support/agent-context/config.toml
Verify it exists:
ls -l ~/Library/Application\ Support/agent-context/config.toml
4. Set up an embedding provider
agent-context needs an embedding provider for semantic indexing and semantic search. Choose one of these:
[!WARNING] If you choose a hosted provider,
agent-contextwill send codebase content to that provider to generate embeddings. That means Voyage and OpenAI will receive text derived from the repositories you index. If that is not acceptable for your environment, use Ollama instead.
Voyage
- Best fit if you want a hosted provider that is strong on code and retrieval tasks.
- Start here:
- docs: Voyage API key and installation
- dashboard: Voyage dashboard
- What to do:
- create a Voyage account
- open the API keys section in the dashboard
- create a secret key
- store the key where the Homebrew service can read it
- Good default:
- keep the README example config and use Voyage if you want the simplest hosted setup for code search
Recommended Homebrew service setup:
[embedding.voyage]
api_key_env = "VOYAGE_API_KEY"
key_file = "~/Library/Application Support/agent-context/voyage_key"
mkdir -p ~/Library/Application\ Support/agent-context
printf '%s\n' 'YOUR_VOYAGE_KEY' > ~/Library/Application\ Support/agent-context/voyage_key
chmod 600 ~/Library/Application\ Support/agent-context/voyage_key
OpenAI
- Best fit if you already use the OpenAI API and want hosted embeddings without adding another provider account.
- Start here:
- embeddings guide: OpenAI embeddings guide
- API keys: OpenAI API keys
- What to do:
- create or use an OpenAI API account
- create an API key
- make that key visible to the Homebrew service
- Good default:
- use one of the current
text-embedding-3models and keep it stable once you start indexing
- use one of the current
Recommended Homebrew service setup:
[embedding.openai]
api_key_env = "OPENAI_API_KEY"
key_file = "~/Library/Application Support/agent-context/openai_key"
base_url = "https://api.openai.com/v1"
mkdir -p ~/Library/Application\ Support/agent-context
printf '%s\n' 'YOUR_OPENAI_KEY' > ~/Library/Application\ Support/agent-context/openai_key
chmod 600 ~/Library/Application\ Support/agent-context/openai_key
Ollama
- Best fit if you want a fully local provider instead of a hosted API.
- Start here:
- embeddings docs: Ollama embeddings
- install Ollama: ollama.com/download
- model library: Ollama library
- What to do:
- install Ollama
- start the Ollama server
- pull an embedding model locally before continuing
- Recommended models:
embeddinggemma- good default if you want the simplest current Ollama recommendation
- model page: embeddinggemma
qwen3-embedding- good option if you want a newer general-purpose embedding model from the current Ollama recommendations
- model page: qwen3-embedding
all-minilm- good option if you want a smaller, lighter local model
- model page: all-minilm
- Example:
ollama pull embeddinggemma
curl http://localhost:11434/api/embed -d '{"model":"embeddinggemma","input":"hello world"}'
If you have never used an embedding provider before:
- choose Voyage if you want the easiest hosted path
- choose OpenAI if you already use OpenAI API keys elsewhere
- choose Ollama if you want everything local and are comfortable running one more local service
Your agent-context init --provider ... choice should match the provider you actually plan to use.
5. Validate the setup
agent-context doctor
Do not continue until doctor reports no blocking issues.
6. Start the local service
brew services is the preferred service layer.
brew services start agent-context
brew services list | grep agent-context
curl http://127.0.0.1:8765/health
7. Print MCP config for your client
agent-context print-mcp-config --client codex
Supported values:
codexclaudecopilot
8. Give your agent the right instructions
After the MCP is connected, add something like this to your global agent instructions or repo-local AGENTS.md / CLAUDE.md:
Use the agent-context MCP as the first step for repository discovery and code search.
- Call list_scopes first in an unfamiliar workspace.
- Use search_symbols for exact definition lookup when the symbol name is known or suspected.
- Use search_code for broader semantic or hybrid discovery.
- Treat search_code snippets as discovery hints, not authoritative reads.
- Use search_text for exact strings, identifiers, test names, and log lines once the repo, file, or subtree is known.
- Use get_file_outline when the file is known and you need structure.
- Use prepare_edit_target only immediately before patching a known location.
- Do not use prepare_edit_target for broad reading, overview, or header scanning.
- Fall back to shell rg, sed, or bat only for regex-heavy cases, unindexed files, or MCP outages.
9. Index your repos
agent-context refresh-all
# or for a clean rebuild
agent-context reindex-all
10. Install post-commit hooks
agent-context install-hook /absolute/path/to/repo
What Agents Get
The MCP server is the main product surface.
Current tools:
list_scopesindex_codebasesearch_symbolssearch_codesearch_textget_file_outlineprepare_edit_targetexplain_searchclear_indexget_indexing_status
Preferred routing:
- use
list_scopesfirst in an unfamiliar workspace - use
search_symbolsfirst for exact definition lookup - use
search_codefor broader semantic or hybrid discovery; treat returned snippets as discovery hints, not authoritative reads - use
search_textfor exact strings, identifiers, test names, and log lines inside a known repo, known file, or bounded repo-relative tree instead of narrowrg - use
get_file_outlineonce the target file is known and you need structure rather than broad file reads - use
prepare_edit_targetonly when the exact patch location is already known; it is the final pre-patch step, not an overview or header-scanning tool - fall back to shell
rg/sed/batonly for regex-heavy cases, unindexed files, or MCP outages
Example Agent Workflow
Typical flow for a code-assistant task:
list_scopessearch_symbolsfor an exact symbol if one is knownsearch_codefor broader behavior or semantic discoverysearch_textwhen a known repo, file, or subtree needs exact literal confirmationget_file_outlineon the chosen fileprepare_edit_targetonly after the exact patch location is known- use shell reads only if regex is required or MCP exact inspection is unavailable
CLI Commands
Setup and repair:
agent-context initagent-context doctoragent-context install-hook <repo>agent-context print-mcp-config --client codex|claude|copilotagent-context prune-stale-vector-collections(dry-run)agent-context prune-stale-vector-collections --applyagent-context release-vector-collections
Indexing and serving:
agent-context refresh-one <scope-or-absolute-repo>agent-context refresh-allagent-context reindex-allagent-context search <scope-or-absolute-repo> "<query>"agent-context list-toolsagent-context serve --listen 127.0.0.1:8765 --config ~/Library/Application\ Support/agent-context/config.toml
Configuration
The canonical config shape is:
snapshot_path = "~/Library/Application Support/agent-context/state/snapshot.json"
index_root = "~/Library/Application Support/agent-context/index-v1"
default_group = "workspace"
[embedding]
provider = "voyage" # or openai / ollama
model = "voyage-code-3"
[embedding.voyage]
api_key_env = "VOYAGE_API_KEY"
[milvus]
address = "127.0.0.1:19530"
[freshness]
# audit_interval_secs = 900
[search]
max_concurrent_requests = 2
max_concurrent_repo_searches = 4
max_concurrent_lexical_tasks = 2
max_concurrent_dense_tasks = 2
max_warm_repos = 4
[[groups]]
id = "workspace"
label = "Workspace"
repos = [
"/absolute/path/to/repo",
]
See the full template in config.example.toml.
Under The Hood
This is the technical part that sits below the feature surface:
- Rust MCP server with a shared local HTTP bridge
- Milvus for dense semantic retrieval
- Tantivy for lexical, path-aware, and exact-token retrieval
- SQLite for symbol metadata and file outlines
- Hybrid search planner that routes and fuses dense, lexical, and symbol signals
- Bounded warm-reader cache and global search budgets to keep latency and memory under control
Agent Notes
If an agent is performing installation or recovery:
- prefer absolute repo paths
- run
doctorbefore and after service installation - if
doctorreports stale vector collections, runprune-stale-vector-collectionsfirst, then rerun with--applyafter reviewing the names - if
doctorreports too many loaded vector collections, runrelease-vector-collections; it unloads Milvus memory without deleting indexes - use
print-mcp-configinstead of hand-writing client snippets - assume provider or model changes require
reindex-all - prefer
install-hookover manual hook editing
