InvoiceLens MCP

An MCP server for invoice PDFs and vendor research. It exposes five tools that any MCP client can use: a LangGraph agent in another project, Claude Desktop, or Claude Code.

The same operations are also exposed as a REST API (/ingest, /search, /extract, /company-financials, /web-search) from the same process, backed by the same index.

Architecture

flowchart TB
    subgraph clients[Clients]
        LG[LangGraph agent<br/>any project]
        CD[Claude Desktop / Code<br/>stdio]
        HC[HTTP client<br/>curl, Swagger UI]
    end
    subgraph server[InvoiceLens server]
        MCP[MCP server · FastMCP<br/>5 tools, stdio + HTTP]
        API[REST API · FastAPI<br/>/ingest /search /extract …]
        SVC[InvoiceLensService<br/>single shared core]
        ING[Ingestion<br/>parse → hybrid chunk → embed]
        RET[Retriever<br/>query → top-k]
        EXT[Extractor<br/>LLM + rules fallback → validator]
        MKT[Market data + web search<br/>cached, actionable errors]
        FAISS[(FAISS IndexFlatIP<br/>per collection, on disk)]
        META[(chunk + document<br/>metadata, original PDFs)]
    end
    AOAI[Azure OpenAI<br/>embedding-3-large · gpt-4o]
    EXTAPI[FMP · Tavily]
    LG --> MCP
    CD --> MCP
    HC --> API
    MCP --> SVC
    API --> SVC
    SVC --> ING & RET & EXT & MKT
    ING --> FAISS & META
    RET --> FAISS
    EXT --> META
    ING & RET & EXT -.-> AOAI
    MKT -.-> EXTAPI

Both interfaces are thin adapters over one InvoiceLensService, so they can't drift apart. A test asserts that MCP and REST return identical results for the same call.

The agent graph (agent/)

flowchart LR
    S([start]) --> A[agent<br/>LLM + 5 MCP tools]
    A -- tool calls --> T[tools<br/>MCP ToolNode]
    A -- no tool calls --> E([answer, cited])
    T -- extract_invoice --> V{{validate<br/>plain code}}
    T -- other tools --> A
    V -- valid, or retry with errors --> A
    V -- failed twice --> R[flag for review] --> E2([needs human review])

The validate node is deterministic code, not an LLM. When an extraction fails the arithmetic checks, it sends the exact errors back to the agent ("Line items sum to 5,700.00 but subtotal is 5,900.00"). The agent then re-extracts with that feedback. If the second attempt also fails, the graph stops and flags the invoice for human review, rather than letting the agent present numbers that don't add up. Some invoices really are wrong; samples/initech_* is one.

Related MCP server: doc-intel MCP server

Vendor research: market data and web search

Two tools look outward, so an agent can go from "who sent this invoice?" to "what do we know about them?"

Numbers deliberately don't come from web search: snippets can be days old or quote the wrong currency. The tool descriptions and the agent's system prompt both steer the model to the right tool.

Setup. Both keys are optional; without one, its tool returns a clear "set INVOICELENS_…_API_KEY" error and everything else keeps working.

INVOICELENS_TAVILY_API_KEY=tvly-...      # https://app.tavily.com
INVOICELENS_FMP_API_KEY=...              # https://site.financialmodelingprep.com

curl "http://127.0.0.1:8765/company-financials?company=Microsoft"
curl -H 'content-type: application/json' -d '{"query":"Microsoft cloud growth","topic":"news","time_range":"month"}' \
     http://127.0.0.1:8765/web-search

Know the free tiers (as of October 2026):

• FMP: 250 calls a day, and US-listed securities only. Non-US companies resolve through a US listing where one exists (Infosys → INFY ADR); otherwise they need a paid plan. Name searches prefer US exchanges for this reason. Lookups are cached for 10 minutes (one company costs 2–3 calls), and if the growth endpoint isn't in your plan, the profile still returns with a note.

• Tavily: 1,000 credits a month on the free tier. Each search uses one credit (search_depth: basic).

• Private companies, like the fictional vendors in samples/, aren't listed. The financials tool says so and points the agent to web search instead. To demo the market tools, ask about a real US-listed company.

Market data is returned with its source, retrieved_at timestamp and a "not investment advice" note, and the API key travels in a header, never in the URL.

Hybrid chunking

A pure fixed-size splitter cuts invoices in the worst places: through a line-item table, or between Invoice Number: and its value. A pure structural splitter makes wildly uneven chunks. InvoiceLens does both, in order.

1. Structure. Each page's elements are classified in reading order:

2. Size. Prose is packed into windows of at most 512 tokens with 64 tokens of sentence-level overlap. Sentences are never cut unless a single sentence exceeds the window.

Every chunk is embedded with a contextual header (Document: acme.pdf | Page 1 | totals | Section: …), so a terms paragraph is still findable by its vendor.

On the samples, every invoice produces header → table → totals → text. The Northwind terms page (about 180 tokens) is one text chunk under Section: Terms and Conditions; longer documents are windowed with overlap (see test_long_prose_is_windowed_with_overlap).

Quick start

pip install -e ".[agent,dev]"
cp .env.example .env              # add Azure OpenAI details for real embeddings + LLM extraction
invoicelens-serve                 # REST + MCP on http://127.0.0.1:8765  (Swagger at /docs)

curl -F file=@samples/northwind_logistics_2026-04.pdf http://127.0.0.1:8765/ingest
curl -H 'content-type: application/json' -d '{"query":"late payment penalty"}' http://127.0.0.1:8765/search

With no keys set, InvoiceLens runs fully offline using a hashing embedder and a rule-based extractor. That's how the tests and CI run, and why the server always starts. The hashing embedder is lexical, not semantic, so use Azure OpenAI for real retrieval quality. /health reports which providers are active.

Use it from another project

That project needs no InvoiceLens code. It only needs the server's URL and langchain-mcp-adapters:

from langchain.agents import create_agent          # pip install langchain langchain-mcp-adapters
from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "invoicelens": {
        "url": "http://127.0.0.1:8765/mcp",
        "transport": "streamable_http",
        # "headers": {"Authorization": "Bearer <INVOICELENS_API_TOKEN>"},
    }
})
tools = await client.get_tools()   # the five invoicelens_* tools
agent = create_agent(llm, tools)

To get the self-correcting validation loop, copy agent/graph.py instead and call build_graph(llm, tools). Or run the bundled one:

python -m agent.run "What is the total on the Acme invoice?"
python -m agent.run --stdio "Which invoice charges a late payment penalty?"   # launches the server itself

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "invoicelens": { "command": "invoicelens-mcp", "args": ["--transport", "stdio"] }
  }
}

Things to know when sharing one server

• One index, many clients. Everything ingested is searchable by every client. Pass collection (e.g. "client-a") to keep separate indexes.

• Sending files. Over stdio, tools can take a server-side path. A remote server can't see your disk, so send pdf_base64, and set INVOICELENS_ALLOW_LOCAL_PATHS=false on any networked deployment.

• Auth. Bound to 127.0.0.1, the MCP SDK's DNS-rebinding protection only accepts localhost Host headers. Bound to 0.0.0.0 (Docker, cloud) it doesn't, so set INVOICELENS_API_TOKEN to require Authorization: Bearer … on REST and MCP. For multi-user production, put it behind an OAuth gateway such as Azure API Management with Entra ID.

• Keys stay on the server. Azure OpenAI credentials live in the server's .env only; client projects never see them.

Design decisions and safety nets

Version notes

The project pins MCP SDK 1.x (mcp>=1.30,<2) on purpose. MCP SDK 2.x renamed FastMCP to MCPServer and changed internals, and langchain-mcp-adapters (the LangGraph bridge, 0.3.2 at the time of writing) doesn't support 2.x yet. Pinning 1.x keeps the server usable from any LangGraph project today.

Tests

pytest -q          # 74 tests, offline, ~8 s

Project layout

src/invoicelens/
  parsing.py      PDF -> text blocks + tables, in reading order
  chunking.py     hybrid chunker
  embeddings.py   Azure OpenAI / OpenAI text-embedding-3-large, offline hashing embedder
  store.py        FAISS + metadata per collection, persisted
  extraction.py   LLM structured outputs, rule-based fallback
  validation.py   arithmetic and date checks
  service.py      the shared core
  external.py     Tavily web search, FMP market data
  mcp_server.py   FastMCP: 5 tools, stdio + Streamable HTTP
  api.py          FastAPI + MCP mounted at /mcp
agent/            LangGraph agent (an MCP client; imports nothing from invoicelens)
samples/          synthetic invoices + their generator
tests/

Sample data

samples/ holds four synthetic invoices generated by samples/generate_samples.py. No real company data is included. Initech's stated subtotal is deliberately wrong, and Northwind has a terms-and-conditions page.