doc-intel MCP server

An MCP server that exposes the doc-intel-agent document-extraction pipeline to AI agents (Claude Desktop, Claude Code, or any MCP client). The pipeline extracts structured data from PDFs where every field carries a computed confidence score and provenance (page + bounding box + verbatim source span) — and this server's job is to make sure that uncertainty survives the protocol boundary instead of being flattened away.

Companion repo: the extraction pipeline itself (LangGraph, three-signal confidence scoring, eval harness with measured silent-error rates) lives in doc-intel-agent. This package reads the same database and reuses its models — installing this package pulls it in automatically.

Design points

Confidence must survive the boundary. A total is never returned as 45300. It is returned as:

{"value": "45300.0", "confidence": 0.94, "verified": true, "page": 3}

If the MCP layer flattened uncertainty away, the agent on the other side would hallucinate with our data. Every value-returning tool keeps this envelope.

Return shapes are context-budget-aware. Tool results land in a model's context window — that is the scarce resource, not bandwidth. List tools paginate with explicit {"truncated": true, "next_cursor": ...}; long text truncates with a marker; summaries come with drill-down tools rather than 40KB dumps.

Tool descriptions are prompts. Each docstring states what the tool does, when to use it, and when not to — naming the better alternative ("Do NOT use search_documents to fetch a document you already have an ID for — use get_extraction").

Write tools have a different posture. Mutations are clearly marked, require explicit IDs (no bulk-by-predicate — nothing like "approve everything above 0.8"), and every mutation is logged with the calling client's identity. Corrections double as gold labels for the pipeline's eval harness.

All three MCP primitives, not just tools — most community servers ship tools only; resources let the calling agent understand the data model before querying it.

Surface

Kind	Name	Why it exists
tool	search_documents(query, doc_type?, vendor?, date_from?, date_to?, min_amount?, limit, cursor?)	hybrid content + metadata search; paginated
tool	get_extraction(document_id, include_low_confidence=False, fields?)	structured result; uncertain data is opt-in
tool	get_field_provenance(field_id)	page, bbox, verbatim span — the agent can show its work
tool	list_review_queue(limit, max_confidence, doc_type?)	agent triages on a human's behalf
tool	compare_documents(doc_id_a, doc_id_b)	invoice-vs-PO mismatch, a real BFSI use case
tool ✏️	approve_field(field_id, note?)	mutation; explicit ID required; logged
tool ✏️	correct_field(field_id, new_value, note?)	mutation; logged as a gold-label review action
tool ✏️	process_document(file_path, doc_type_hint?)	returns a job id immediately, does not block
tool	get_job_status(job_id)	poll for the resulting document_id
resource	schema://invoice, schema://purchase_order, schema://bank_statement	derived from the live Pydantic models — cannot drift
resource	stats://pipeline	throughput, review-queue depth, cost
resource	doc://{document_id}/text	raw document text with explicit truncation
prompt	audit_invoice_batch(vendor, date_from, date_to)	duplicate/anomaly audit workflow
prompt	reconcile_po(invoice_id, po_id)	line-item reconciliation workflow

Install / run

pip install "doc-intel-mcp-server @ git+https://github.com/avinashbadgu/doc-intel-mcp-server.git"

# stdio (local clients — Claude Desktop, Claude Code)
python -m mcp_server.server

# streamable HTTP at http://127.0.0.1:8765/mcp
python -m mcp_server.server --http        # or MCP_TRANSPORT=http

Environment: DATABASE_URL (defaults to local SQLite docintel.db — point it at the same DB the pipeline writes), MCP_HOST / MCP_PORT for HTTP, ANTHROPIC_API_KEY optional (enables real-model process_document; without it the deterministic offline extractor runs).

Client config

Claude Code:

claude mcp add doc-intel -- python -m mcp_server.server

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "doc-intel": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "path/to/your/checkout"
    }
  }
}

Manual test (MCP Inspector)

python -m mcp_server.server --http
npx @modelcontextprotocol/inspector

Transport Streamable HTTP, URL http://127.0.0.1:8765/mcp. Then: search_documents {"query": "INV-2026"} → note the confidence envelope → get_extraction → note fields_omitted_pending_review → re-run with include_low_confidence: true → get_field_provenance on a queue entry → page + bbox + span.

The end-to-end demo in Claude Code: "find every invoice from vendor Acme over 1,000, check which ones have unverified totals, and tell me which need human review" — the model chains search_documents → get_extraction → get_field_provenance and answers with page and bounding-box citations.

Status / roadmap

Built on the MCP Python SDK 1.28 (spec 2025-06-18), tested via the SDK's in-memory client session in the companion repo. Next: SDK v2 / 2026-07-28 spec migration, and OAuth 2.1 on the HTTP transport (current auth story: stdio + env credentials at startup).