Integrating with MCP Clients
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Integrating with Model Context Protocol (MCP) clients allows Claude Context to function as a powerful backend for AI agents and coding assistants like Claude Code, Cursor, and Claude Desktop. By acting as an MCP server, the @zilliz/claude-context-mcp package enables these clients to semantically index and search entire codebases, providing them with deep, context-aware information that exceeds the limitations of standard context windows.
Sources: README.md:16-19, packages/mcp/README.md:1-5
The integration relies on a standardized communication protocol using stdio transport. The MCP server exposes specific tools to the client, which the client can call to perform actions such as indexing directories, searching for code snippets using natural language, and managing the index state. This architecture ensures that large codebases are indexed efficiently in a vector database (like Milvus or Zilliz Cloud) while only the most relevant snippets are passed to the AI model's context.
Sources: packages/mcp/src/index.ts:162-167, packages/mcp/CONTRIBUTING.md:46-50
Architecture and Data Flow
The MCP server acts as a bridge between the AI client and the core indexing engine. It leverages the @zilliz/claude-context-core for heavy lifting, including embedding generation and vector database operations.
Integration Workflow
The following diagram illustrates how an MCP client interacts with the Claude Context MCP server to retrieve relevant code context.
The workflow ensures that the AI client receives high-quality context without needing to manage the complexities of vector search or file chunking.
Sources: packages/mcp/src/index.ts:25-50, README.md:214-219
Server Configuration and Startup
The MCP server requires specific environment variables to connect to embedding providers and vector databases. It uses a configuration factory to assemble these settings before starting the StdioServerTransport.
Core Configuration Options
The following table summarizes the critical configuration elements required for a successful integration.
| Category | Environment Variable | Description | Default / Required |
|---|---|---|---|
| Provider | EMBEDDING_PROVIDER | OpenAI, VoyageAI, Gemini, or Ollama | OpenAI |
| Model | EMBEDDING_MODEL | Specific model for embeddings (e.g., text-embedding-3-small) | Provider Dependent |
| Auth | OPENAI_API_KEY | API Key for OpenAI services | Required for OpenAI |
| Auth | MILVUS_TOKEN | API Key/Token for Zilliz Cloud | Required |
| Network | MILVUS_ADDRESS | Public endpoint for the Milvus database | Optional (can auto-resolve) |
Sources: packages/mcp/src/config.ts:89-110, packages/mcp/README.md:46-70
Startup Process Logic
- Initialize Transport: The server sets up
StdioServerTransportto communicate via standard input/output. - Setup Tools: Tools like
index_codebaseandsearch_codeare registered with the MCP SDK. - Background Sync: The server starts a
SyncManagerto handle background updates of the codebase index.
Sources: packages/mcp/src/index.ts:156-173, packages/mcp/src/config.ts:114-130
Exposed Tools for Clients
MCP clients interact with the system through four primary tools. Each tool is defined with a Zod-validated input schema to ensure technical accuracy during the integration.
Tool Summary Table
| Tool Name | Purpose | Primary Parameters |
|---|---|---|
index_codebase | Indexes a directory into the vector database | path (absolute), splitter, force |
search_code | Performs semantic natural language search | path, query, limit, extensionFilter |
get_indexing_status | Returns the current progress of an indexing task | path |
clear_index | Removes all indexed data for a specific directory | path |
Sources: packages/mcp/src/index.ts:85-154, packages/mcp/README.md:270-295
Indexing Logic
When a client calls index_codebase, the server initiates an AST-based or character-based splitting process. It utilizes Merkle trees to detect file changes, allowing for incremental indexing rather than full re-indexing of every file.
Sources: packages/mcp/src/index.ts:100-110, packages/mcp/CONTRIBUTING.md:52-60
Specific Client Configuration Examples
Different MCP clients require specific configuration formats, typically JSON or TOML, to point to the server's entry point (dist/index.js).
Claude Code and Cursor Setup
For most modern clients, the configuration defines the command (node or npx), the path to the server, and the necessary environment variables.
{
"mcpServers": {
"claude-context": {
"command": "npx",
"args": ["-y", "@zilliz/claude-context-mcp@latest"],
"env": {
"OPENAI_API_KEY": "sk-your-key",
"MILVUS_TOKEN": "your-zilliz-token"
}
}
}
}
Sources: README.md:104-120, packages/mcp/README.md:143-158
Claude Code CLI Command
Integration can also be performed via the CLI for Claude Code:
claude mcp add claude-context \
-e OPENAI_API_KEY=sk-your-key \
-e MILVUS_TOKEN=your-token \
-- npx @zilliz/claude-context-mcp@latest
Sources: README.md:65-70, packages/mcp/README.md:118-124
Implementation Details
The server implementation strictly redirects console.log and console.warn to stderr. This is a critical requirement for MCP integrations because stdout is reserved exclusively for the JSON-RPC protocol messages. If standard logs are sent to stdout, the client-server connection will break.
// packages/mcp/src/index.ts:5-15
const originalConsoleLog = console.log;
console.log = (...args: any[]) => {
process.stderr.write('[LOG] ' + args.join(' ') + '\n');
};
Sources: packages/mcp/src/index.ts:5-15, packages/mcp/CONTRIBUTING.md:46-50
Conclusion
Integrating with MCP clients transforms Claude Context into a seamless extension of the developer's workflow. By exposing semantic search and indexing tools through the Model Context Protocol, the server allows AI agents to navigate millions of lines of code efficiently. The combination of stdio transport, hybrid search, and flexible embedding provider support makes it a robust solution for providing high-fidelity codebase context to any MCP-compliant client.