Claims Assistant — an MCP server

A tiny, self-contained project that teaches how MCP works, end to end, with no database, no API keys, and no internet.

The story

Meera runs the motor-claims desk at a general insurer. All day, agents and customers ask her team the same thing: “What’s the status of my claim? Is it approved? How much will I get?” She wants an AI assistant that answers instantly. But the AI has no idea whether claim CLM-4471 is approved — that lives only in the claims system. So she gives the AI a tool to look it up. That tool is the MCP server we build here.

Why this example works

A claim’s status is a fact the AI cannot guess — it exists only in our records. So the AI has no choice but to call our tool. That is the real reason MCP exists: to connect a model to knowledge it could never have on its own.

The two files (so far)

Keeping them separate is deliberate: the data (the concept) is one file, the MCP wrapping (the application) is another.

---

Project 1 : Claims Status MCP Server

Follow these steps in order. Each one confirms the layer beneath it before adding the next — so if something breaks, you know exactly where.

Step 1 — Install the MCP SDK

Python 3.10 or newer is required.

pip install "mcp[cli]"

Step 2 — Check the data works (no MCP yet)

Run the plain lookup on its own first. This proves the claims data is correct before we involve any AI.

python3 claims_data.py

You should see records printed for CLM-4471 (Approved), CLM-5522 (Under Review), CLM-6033 (Rejected), and CLM-9999 (not found). If this fails, it is a plain Python problem — fix it before touching MCP.

Step 3 — Test the server with the MCP Inspector

The Inspector is a small web tool that connects to your server exactly like a real AI app would — but shows you everything happening underneath. It IS a client (the same role VS Code or Claude Desktop plays), just without an AI model. Using it, you play the part of the AI: you pick the tool and type the input by hand.

Launch it

Run this from inside the project folder (where server.py lives):

npx @modelcontextprotocol/inspector python3 claims_server.py

⚠️ Do not use mcp dev server.py unless you have uv installed. On a plain pip setup, mcp dev tries to launch through uv and fails