MCP Server Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) server for Claude Context is a specialized integration layer that enables AI assistants and agents (such as Claude Code, Cursor, or Claude Desktop) to perform semantic searches across local codebases. It acts as a bridge between the core indexing engine and the MCP ecosystem, allowing agents to understand millions of lines of code by retrieving only the most relevant snippets as context.
The server implements the standard MCP protocol using stdio transport for maximum compatibility. It facilitates hybrid search (combining BM25 and dense vector search), incremental indexing via Merkle trees, and syntax-aware code chunking. By storing codebase representations in a vector database (Milvus/Zilliz), it provides a cost-effective way to provide deep context without overloading the LLM's context window.
Sources: packages/mcp/README.md:1-20, packages/mcp/src/index.ts:50-100, packages/core/README.md:10-25
Architecture and Components
The MCP server is structured as a TypeScript application that encapsulates the Context class from the @zilliz/claude-context-core package. It initializes various managers to handle specific tasks such as configuration, tool handling, and codebase synchronization.
System Components
| Component | Responsibility |
|---|---|
| ContextMcpServer | The main entry point that coordinates the MCP SDK server, transports, and core logic. |
| ToolHandlers | Manages the logic for specific MCP tools like indexing and searching. |
| SyncManager | Handles background synchronization and incremental updates of indexed files. |
| SnapshotManager | Manages the persistence of indexed codebase states and progress. |
| Core Engine | The underlying @zilliz/claude-context-core which performs embedding and vector DB operations. |
Sources: packages/mcp/src/index.ts:25-48, packages/mcp/CONTRIBUTING.md:40-60
Operational Flow
The diagram below illustrates the initialization and execution flow of the MCP server when receiving a tool request from a client.
The flow shows the interaction between the client interface and the internal core engine components via the MCP standard.
Sources: packages/mcp/src/index.ts:167-195, packages/mcp/CONTRIBUTING.md:65-75
Available Tools
The server exposes four primary tools to the AI agent, defined within the ListToolsRequestSchema handler.
1. index_codebase
Indexes a directory for hybrid search. It supports AST-based or LangChain-based splitting.
- Key Parameters:
path(absolute),force(re-indexing),splitter,customExtensions,ignorePatterns. - Behavior: Typically used when a search fails because a codebase hasn't been processed yet.
2. search_code
Performs natural language queries against an indexed codebase.
- Key Parameters:
path,query,limit(max 50),extensionFilter. - Capability: Retrieves relevant functions, classes, or patterns across the entire project.
3. clear_index
Removes the search index for a specific absolute path.
4. get_indexing_status
Returns progress percentages for active indexing tasks or a completion status for finished ones.
Sources: packages/mcp/src/index.ts:103-165, packages/mcp/README.md:250-290
Configuration and Environment
The server relies on environment variables for sensitive credentials and provider selection. Configuration is centralized in packages/mcp/src/config.ts.
Embedding Provider Support
The server supports four primary embedding providers, each requiring specific environment variables:
| Provider | Required Environment Variables | Default Model |
|---|---|---|
| OpenAI | OPENAI_API_KEY | text-embedding-3-small |
| VoyageAI | VOYAGEAI_API_KEY | voyage-code-3 |
| Gemini | GEMINI_API_KEY | gemini-embedding-001 |
| Ollama | OLLAMA_HOST (Optional) | nomic-embed-text |
Sources: packages/mcp/src/config.ts:55-120, packages/mcp/README.md:40-100
Vector Database Integration
The server connects to Milvus or Zilliz Cloud.
MILVUS_ADDRESS: The endpoint for the database.MILVUS_TOKEN: Authentication token (can be used to auto-resolve addresses on Zilliz Cloud).
Sources: packages/mcp/src/config.ts:125-135, packages/core/README.md:30-45
Codebase Snapshot System
The server tracks codebase states using a versioned snapshot system. This allows the server to maintain awareness of which paths are indexed even across restarts.
The class diagram represents the structured state tracking for codebases as defined in the V2 snapshot format.
Sources: packages/mcp/src/config.ts:25-52
Implementation Details
Console Output Redirection
A critical implementation detail in packages/mcp/src/index.ts is the immediate redirection of console.log and console.warn to process.stderr. This prevents standard log messages from polluting the stdout stream, which is reserved strictly for the MCP JSON-RPC protocol.
// packages/mcp/src/index.ts:4-14
const originalConsoleLog = console.log;
const originalConsoleWarn = console.warn;
console.log = (...args: any[]) => {
process.stderr.write('[LOG] ' + args.join(' ') + '\n');
};
console.warn = (...args: any[]) => {
process.stderr.write('[WARN] ' + args.join(' ') + '\n');
};
Sources: packages/mcp/src/index.ts:4-14
Startup Sequence
- Config Initialization: Loads environment variables and validates provider keys.
- Manager Initialization: Instances of
SnapshotManager,SyncManager, andToolHandlersare created. - Snapshot Loading: Existing codebase snapshots are loaded from the filesystem.
- Transport Connection: The server connects via
StdioServerTransport. - Background Sync: Starts the
SyncManagerto monitor indexed codebases for changes.
Sources: packages/mcp/src/index.ts:40-75, packages/mcp/src/index.ts:197-210
Conclusion
The MCP Server provides a robust, standardized interface for AI agents to interact with the Claude Context core. By abstracting the complexities of vector search and incremental indexing into simple MCP tools, it enables high-performance code understanding with minimal token overhead. Its flexible configuration system ensures compatibility with both local (Ollama/Milvus) and cloud-based (OpenAI/Zilliz) AI infrastructures.
Sources: packages/mcp/README.md:300-320, evaluation/README.md:25-40