Document Search — an MCP server

Wraps document ingestion and retrieval (the same chunking + Voyage embedding + Chroma logic from Project 2) as an MCP server — so Claude Desktop or Claude Code can search your own documents directly, as a native tool call, instead of you running a separate CLI.

This is Project 4 in a self-directed AI engineering learning path. It builds on Project 2 (RAG) and Project 3 (tool use) — MCP is essentially "tool use, standardized so any client can use your tools, not just code you wrote yourself."

The key design decision, and why it matters

Unlike Project 2's doc_chat.py, this server never calls the Claude API to generate an answer. It only retrieves and returns relevant chunks. This is intentional, not a missing feature:

When Claude Desktop (or Claude Code) calls search_documents, it's already a Claude model in the loop — the client itself. It receives the retrieved chunks as a tool result and writes the final answer using its own reasoning, the same way it would use any other tool's output. Having the server also call Claude to generate an answer would be redundant — two models doing the same generation job — and would take control away from the client, which is supposed to decide how to use retrieved context, not just relay someone else's answer.

This is the real shift MCP represents: in Project 2, you wrote the code that calls Claude. In Project 4, Claude is the code calling your tool. The server's only job is to be a good, honest data source.

Setup

pip install -r requirements.txt

$env:VOYAGE_API_KEY = "your-voyage-key"

(No ANTHROPIC_API_KEY needed for the server itself — see above. You'll still need one configured wherever Claude Desktop/Code itself runs, but that's separate from this server.)

Connecting it to Claude Code

claude mcp add doc-search -- python /full/path/to/mcp_doc_server.py

Use the full absolute path to the script — relative paths won't resolve correctly once Claude Code launches it as a subprocess from a different working directory.

Then, in a Claude Code session, you can just ask naturally:

"Ingest the documents in ./sample_docs, then tell me the meal reimbursement policy."

Claude Code will call ingest_documents, then search_documents, then write the answer itself — the same multi-step tool chaining you saw in Project 3, except now the tool is your own MCP server instead of a Python function baked into the same script.

Connecting it to Claude Desktop

Add this to your Claude Desktop MCP config file (claude_desktop_config.json — check Claude Desktop's settings for its exact location on your system):

{
  "mcpServers": {
    "doc-search": {
      "command": "python",
      "args": ["/full/path/to/mcp_doc_server.py"],
      "env": {
        "VOYAGE_API_KEY": "your-voyage-key"
      }
    }
  }
}

Restart Claude Desktop after editing the config. You should see "doc-search" appear as an available tool source in the app.

Testing without a live MCP client

fastmcp ships an in-process test client, which is what verified this server before you ever connect it to Claude Desktop:

import asyncio
from fastmcp import Client
from mcp_doc_server import mcp

async def main():
    async with Client(mcp) as client:
        tools = await client.list_tools()
        print(tools)

asyncio.run(main())

This calls the real MCP protocol layer — tool discovery, schema generation, invocation — without needing a full Claude Desktop install or a live API key, which is how the error-path behavior was verified during development.

Design notes

• Tool docstrings are the interface, more so than in Project 3. With direct API tool use, you write a separate description field. With fastmcp, the Python docstring is the description the client sees — meaning writing a clear, accurate docstring isn't just good Python practice here, it's the actual mechanism by which Claude decides when and how to call your tool.
• Global client caching (_voyage_client, _collection). MCP servers are typically long-running processes (started once, called many times), unlike a CLI script that runs once and exits. Creating a new Voyage client or Chroma connection on every single tool call would be wasteful; lazy-initializing them once and reusing them across calls is the correct pattern for a persistent server.
• Tools return strings, not raising exceptions, for expected error cases (missing folder, empty collection) — same philosophy as Project 3's execute_tool. The calling model needs to see and reason about a failure, not have the whole server crash.

What's next

• Add a list_ingested_sources tool so the client can check what's already searchable before deciding whether to re-ingest.
• Add authentication if this were ever exposed over network transport instead of run locally via stdio.
• Package as a proper installable MCP server others could add to their own Claude Desktop config without cloning the repo.