insurance-mcp-poc

A Model Context Protocol server that exposes a life-insurance back office — policy documents, in-flight applications, and product/underwriting rules — as tools an LLM agent can call.

The point of the POC: an agent shouldn't need a bespoke integration per assistant. Implement the domain once as an MCP server, and any MCP-capable client (Claude Code, Microsoft Foundry agents, an internal chat surface) gets the same twenty-four tools with the same contracts.

All data in this repository is synthetic. The schema, products, rules, and documents were invented for this demo and are not derived from any production system.

Built alongside Microsoft Applied Skills: Integrate model context protocol tools with agents in Microsoft Foundry. That assessment covers the client side — attaching an MCP tool to a Foundry agent and validating its calls. This repository is the other half: the server those tools come from.

Quickstart

Requires Docker and Node 20+.

npm install
npm run setup     # starts Postgres+pgvector, seeds the corpus, runs the smoke test

npm run setup is the whole demo: it stands up the database, embeds and inserts 13 documents, then connects to the MCP server as a real MCP client and exercises all twenty-four tools. Expected tail:

Connected. Server exposes 24 tools:
  - search_policy_documents: Search policy documents
  - get_application_status: Get application status
  ...
  - update_requirement_status: Update requirement status
  - reassign_application: Reassign application
...
All tool calls completed.

Then npm run demo walks the chained flow an agent actually performs — see below. Tear down with npm run db:down.

Related MCP server: mcp-langchain-agent

The tools

Twenty-four tools. The design rule: a tool maps to a decision someone makes, not to a table. There is no get_product or list_events here — an agent that has to assemble answers from CRUD primitives burns turns and invents joins. Each tool below answers a question a person actually asks.

Case handling — one known application

Pipeline — across the whole book

Sales and pricing — before a case exists

Knowledge

Sixteen of the twenty-four are read-only and marked readOnlyHint: true. The eight writers differ in a way the annotations capture, because clients use them to decide what needs human confirmation:

None are marked destructive: nothing here deletes, and every writer checks its target exists first and returns a plain "nothing was changed" result rather than throwing.

Guardrails sit at four levels

Worth separating, because only the first is free:

1. Schema — zod becomes JSON Schema and the SDK validates before the handler runs. A missing required field, a string where a number belongs, an age of 999, an unknown enum value: all rejected with a message naming the offending field, and the database is never touched.

2. Existence — every writer confirms its target exists and returns a plain result saying nothing changed, rather than throwing.

3. Domain — the rules no schema can express, because they depend on other rows or on the catalogue. record_underwriting_decision refuses to approve while requirements are outstanding; create_application refuses a product the applicant cannot be issued; withdraw_application refuses a case that has already been decided; amend_application re-checks the revised figure against the product limits and refuses a case that is already closed. Each refusal names what blocked it and which tool moves things forward, so a model can recover instead of stalling.

4. Database — CHECK constraints on every status and class column, foreign keys throughout. The last line of defence if the code above is wrong.

Parameterised SQL everywhere, so '; DROP TABLE applications; -- is searched for as a name and matches nobody.

Try, once connected: "Rowan Kessler's application is stuck — what's it waiting on, and what does the guideline actually say about that requirement?" No single tool answers that. The agent chains all three, and npm run demo shows the same chain step by step:

[1] get_application_status("APP-100242")
      -> Rowan Kessler, age 61, SecureTerm 20-Year
      -> status=pending_underwriting  blocked on: awaiting_paramedical
      -> rules fired: TRM20-AGE-01, TRM20-FACE-01
[2] lookup_product_rules("TRM-20", age=61, face=1500000)
      -> TRM20-AGE-01 [require_evidence]: Applicants over 60 require a paramedical exam…
      -> TRM20-FACE-01 [refer]: Face amounts above $1,000,000 are referred…
[3] search_policy_documents("when is a paramedical examination required")
      -> GUIDE-UW-01  (rrf 0.03154, vector rank 6, text rank 1)

Note step 3: the right document ranked 6th by vector similarity but 1st by full-text. Fusing the two rankings is what surfaces it.

How retrieval works

Hybrid search, fused with Reciprocal Rank Fusion (score = Σ 1/(60 + rank_i)).

Two things forced this design, both found by testing rather than assumed:

• Weighted score blending doesn't work here. Cosine similarity lands around 0.1–0.4 while ts_rank_cd returns values an order of magnitude smaller, so any fixed weighting lets whichever metric happens to be larger dominate. RRF combines ranks, which are scale-free.

• websearch_to_tsquery ANDs every term, so a full-sentence question matches zero documents and the hybrid silently degrades to vector-only. The operators are rewritten to OR, making the lexical side rank by how many query terms a document contains.

Each result reports vector_rank and text_rank alongside the fused score, so it stays visible which half did the work — and a text_rank of null means that document matched no query term.

Connecting it to Claude Code

claude mcp add insurance --  node /absolute/path/to/insurance-mcp-poc/src/index.js

Or add to .mcp.json:

{
  "mcpServers": {
    "insurance": {
      "command": "node",
      "args": ["/absolute/path/to/insurance-mcp-poc/src/index.js"],
      "env": { "DATABASE_URL": "postgres://insurance:insurance@localhost:55432/insurance" }
    }
  }
}

What happens when a client calls a tool

Worth being precise about, because the common mental picture — "the model calls my API" — is wrong in two ways. The model never talks to this server. The client does. And there is no HTTP involved: this server speaks JSON-RPC 2.0 over its own stdin and stdout.

Startup, once per session. The client (Claude Code, a Foundry agent) spawns this process — node src/index.js — and holds its stdin/stdout pipes. It sends initialize, the server replies with protocol version and capabilities, the client sends the initialized notification. Then the client calls tools/list, and the SDK answers with all twenty-four tools: name, description, annotations, and a JSON Schema for the arguments, which it generated from the zod schemas in src/index.js.

The client puts those tool definitions into the model's context. This is the step people skip. The description strings above are not documentation — they are the prompt. A tool the model misunderstands is a tool it calls wrongly, which is why each description says when to reach for this one rather than just what it returns.

Per call. The model emits a tool-use request naming a tool and its arguments. The client — not the model — sends:

// stdin →
{"jsonrpc":"2.0","id":7,"method":"tools/call",
 "params":{"name":"get_application_status","arguments":{"application_number":"APP-100242"}}}

The SDK validates arguments against that tool's schema and rejects the call before the handler runs if it doesn't fit — the model gets a schema error back and can retry. On success it invokes the handler, which runs parameterised SQL against Postgres and returns content blocks:

// ← stdout
{"jsonrpc":"2.0","id":7,"result":{"content":[{"type":"text","text":"{ \"application_number\": ... }"}]}}

The client feeds that result back into the model's context as the tool result, and the model decides what to do next — often calling another tool, which is exactly the chain the demo above walks.

Two distinct failure modes, worth keeping straight:

• A protocol error (unknown tool, malformed arguments) returns a JSON-RPC error. The model sees it went wrong mechanically.

• A tool-level failure — "no application found with number APP-999999" — is a successful JSON-RPC response whose content says so. That's deliberate: it's information the model should reason about, not a crash. add_case_note does this rather than throwing, and writes nothing.

Concurrency and lifetime. Requests carry an id, so the client may have several in flight at once; responses are matched by id, not by order. The process lives as long as the client session and holds a pg connection pool across calls — so state like the pool is per-session, and anything you want durable belongs in Postgres.

How it fits together

MCP client (Claude Code / Foundry agent)
        │  stdio, JSON-RPC
        ▼
   src/index.js          tool definitions + zod input schemas
        │
        ├── src/embed.js  query → vector
        └── src/db.js     pg pool
                 │
                 ▼
        Postgres 16 + pgvector      docker-compose, port 55432

Layout: src/index.js (server and all twenty-four tools) · src/embed.js (embedding) · src/db.js (pool) · db/init.sql (schema + seed) · scripts/seed.mjs (documents + embeddings) · scripts/smoke.mjs (exercises every tool) · scripts/demo.mjs (the chained flow) · scripts/benchmark.mjs (retrieval quality).

The embedding, and why it was measured

src/embed.js runs all-MiniLM-L6-v2 locally, in-process, via transformers.js (ONNX). No API key, no separate service, no Python. Weights (~23MB quantized) download once on first use and cache under ~/.cache/huggingface; the model loads lazily on the first search, so spawning the server stays instant.

It replaced a hashed bag-of-words stand-in, and npm run benchmark records what that was worth — ten questions with a known-correct document, plus paraphrases that share no vocabulary with their target:

The number that matters is the last row. The old embedding scored 0.0000 cosine between "dies by suicide" and "takes their own life" — identical to its score against an unrelated sentence about grace periods, because it matched shared words and those phrases share none. Full-text search has the same ceiling for the same reason. Only a trained model can close that gap, and it is the sole reason the vector half exists: on the ten literal questions, plain Postgres full-text was already beating vector-only 9 to 8.

The one paraphrase still missed lands at rank 3 of 13, not wildly off, and adding a few words of context ("...within two years of the policy date") puts it first. Short queries are ambiguous.

Changing model means changing EMBEDDING_DIM here and vector(384) in db/init.sql, then npm run db:down && npm run db:up && npm run seed. Old vectors are meaningless under a new model.

Notes and limitations

Worth stating plainly, since they're the things a reviewer would ask about:

• No approximate index, on purpose. An early version had ivfflat ... WITH (lists = 10) over 12 rows. It silently returned wrong and short result sets — a single probe scans a near-empty partition. Approximate indexes only pay off at volume. At this corpus size an exact scan is both correct and instant; db/init.sql says where to add HNSW once the corpus justifies it.

• Rules are data, not an engine. underwriting_rules.condition holds plain-language conditions for the agent to reason over. Only the hard limits (age band, face band, state availability) are actually evaluated in code. A production version would compile these to an executable rule set — an LLM interpreting underwriting conditions free-hand is not something to ship.

• No authentication or tenancy. The server trusts its caller completely. Real deployment needs per-caller authorization, since these tools read customer data.

• The model has no idea what insurance is. It learned which phrases keep company with which, which is enough for paraphrase but leaves a known blind spot: antonyms and negation sit close together, because "the premium increased" and "the premium decreased" appear in near-identical contexts. For a policy corpus that is not academic — retrieving the opposite clause and citing it confidently is worse than returning nothing. It is the strongest argument for keeping the full-text half, which is dumb about meaning but never confuses "not covered" with "covered".

• RRF ties are common and were non-deterministic. A document ranked (1,2) scores identically to one ranked (2,1), and without a tie-break Postgres returned whichever the plan emitted first — the same query gave different answers in different contexts. Now broken by vector rank, then doc_id. Worth knowing if you fuse rankings anywhere else.

• node_modules is 401MB. Running the model in-process means shipping ONNX runtime binaries. A hosted embedding endpoint would trade that for an API key and a network hop.

License

MIT