reed-mcp
Your assistant reads your private documents. Nothing leaves the machine.
An MCP server that putsreed — a local-first RAG service with auditedcitations — behind four read-only tools, so any MCP host can answer from yourown documents.
The problem
Connecting an assistant to your documents normally means uploading themsomewhere. For a law firm, a clinic or anyone under GDPR, that is not adeployment detail — it is the reason the project does not happen.
The pieces to avoid it already exist: local models, local vector stores, RAGservices that run on a laptop. What was missing is the join. An assistant thatcan use a local index needs a tool interface, and a RAG service that answersin prose is the wrong shape — the host already has a model, and a better one.What it needs is evidence.
Constraints
- Nothing leaves the machine. The host spawns this server over stdio; theserver talks to reed over loopback. There is no telemetry, no analytics and nothird-party host in the request path.
- The host's model writes the answer. reed-mcp returns ranked passages withfilenames, pages and scores. Attribution is the point: an answer nobody cancheck is worse than no answer.
- Read-only. No upload, no replace, no delete. A tool that cannot destroyanything needs no confirmation dialog and no trust.
- Consumer hardware. A laptop, a 4B model, no GPU cluster.
Architecture
flowchart LR
H["MCP host<br/>(Claude Desktop, Claude Code)"] -->|stdio| M["reed-mcp"]
M -->|"HTTP, loopback"| R["reed"]
R --> Q[("Qdrant<br/>hybrid index")]
R --> O["Ollama<br/>local models"]
M -.->|"evidence + citations"| H
Two decisions carry the design.
A separate process, not a reed subcommand. reed is single-node by design:one process per registry and active index. Importing it as a library whilereed serve is running is exactly what that model forbids, so reed-mcp is aclient, and reed's HTTP surface is the contract between them.
search before ask. reed_search returns evidence and stops; the host'smodel writes the answer and cites it. reed_ask runs reed's own local modelinstead, which costs seconds rather than milliseconds — worth it when a fullylocal generation is the requirement, wasteful when the host was going to writethe answer anyway. This is why reed grewPOST /v1/search: retrievalwithout generation did not exist, and without it every lookup paid for an answerthe caller would discard.
Tools
| Tool | Returns |
|---|---|
reed_search |
Ranked passages: filename, page, section, score, excerpt — plus reed's evidence-threshold verdict (sufficient_evidence), reported rather than applied, so the host decides when to abstain. |
reed_ask |
reed's own answer with [n] markers, its sources, and the result of reed's citation audit. |
reed_list_documents |
The corpus and each document's ingestion status. |
reed_get_document |
One document's status and metadata. |
Results
Measured end to end — a real MCP session over stdio, a real reed, a real index —on an Apple M5 (32 GB) running reed 0.5.1 with EmbeddingGemma and qwen3.5:4bthrough Ollama. 30 searches and 5 asks after a warm-up call:
| Operation | p50 | p95 |
|---|---|---|
reed_search |
159 ms | 252 ms |
reed_ask (local 4B model writes the answer) |
4.8 s | — |
The gap is the whole argument for search: retrieval is thirty times cheaperthan generation, and the host already has a model.
On egress, the honest claim is architectural rather than measured: the only hostreed-mcp opens a connection to is REED_MCP_URL, and its runtime dependenciesare httpx and the MCP SDK. Independent verification is a job for a tool builtfor it — that measurement will be added whenegress-audit exists rather than asserted here.
Run it
You need a running reed 0.5.0 or newer(/v1/search first shipped there; 0.5.1+ recommended) anduv.
Claude Code:
claude mcp add reed -- uvx reed-mcp
Claude Desktop, in claude_desktop_config.json:
{
"mcpServers": {
"reed": {
"command": "uvx",
"args": ["reed-mcp"]
}
}
}
Then ask your assistant something your documents answer. It will search, quoteand cite.
Configuration
Environment variables only — never tool arguments, so nothing sensitive can beelicited through the tool channel:
| Variable | Default | Meaning |
|---|---|---|
REED_MCP_URL |
http://localhost:8000 |
Where reed listens |
REED_MCP_API_KEY |
empty | Sent as X-API-Key; set it when reed runs with REED_API_KEY |
REED_MCP_TIMEOUT_SECONDS |
120 |
Per-request timeout |
REED_MCP_MAX_EXCERPT_CHARS |
2000 |
Longer excerpts are truncated and marked excerpt_truncated |
Security model
- Retrieved text is data, not instructions. Excerpts reach the host's modelas quoted document content, and every tool description says so. reed auditscitations on its side. Neither can semantically sanitise a document: indexwhat you trust, and treat a corpus anyone can write to as untrusted input.
- Credentials never touch the tool channel. They arrive through theprocess environment and are never logged.
- Nothing here can modify your corpus. All four tools are annotatedread-only, and the server implements no write path.
Development
uv sync
uv run pytest
uv run ruff check . && uv run mypy
The unit suite is hermetic — reed is stubbed at the HTTP layer. The end-to-endsuite is not, and that is the point: it launches this package the way a hostdoes and drives it against a real reed. CI runs it against the published reedimage, pinned by digest.
REED_MCP_E2E_URL=http://localhost:8000 uv run pytest e2e
Mocks proved the wiring and missed the bug that mattered — a client bound to anevent loop that had already closed, which broke every tool call in every realhost while the unit suite stayed green. The e2e suite exists because of it.
License
Apache-2.0.
