Content
# MCPantry — Production MCP Server with Usage Analytics
> A real **Model Context Protocol (MCP)** server that exposes governed analytics tools to AI agents (Claude Desktop / Claude Code / any MCP client) — plus a **tool-call analytics** layer that tracks which tools agents actually use, how fast, and how often they fail.
   
MCP is the connective tissue of agentic AI in 2026 — it's how assistants safely reach your data and tools. Very few people have shipped a real, non-trivial MCP server, and almost nobody instruments one. MCPantry does both.
## See it work — Claude calling these tools live
This is a **real capture** of Claude Code connecting to MCPantry over MCP, autonomously calling the `top_n` tool, and answering from the result — while MCPantry's analytics layer logs the call:
> Reproduce it: register the server with the bundled `claude_desktop_config.example.json` (or `--mcp-config`) and ask any MCP client "what are the top regions by revenue?"
---
## The problem
Teams want their AI assistant to answer questions over *their* data ("what were top regions by revenue last week?") without copy-pasting CSVs or giving the model raw DB access. MCP is the standard answer — but a bare MCP example exposing `add(a,b)` proves nothing. And once agents start calling your tools, **you have no idea which tools matter, which are slow, or which error** — there's no observability story for MCP yet.
MCPantry is a genuine analytics MCP server **with** that observability built in.
## Who uses it
- **Platform / data teams** exposing governed metrics to internal AI assistants.
- **AI engineers** building agents that need real tool access (not hallucinated data).
- Anyone who wants **MCP observability** — usage analytics over agent tool calls.
## What it proves (skills)
Real MCP server implementation (FastMCP), tool/registry design, a clean SDK-independent tool layer (unit-testable without a transport), and an **observability layer** (SQLite-backed usage analytics with latency + error tracking). It's the protocol this very assistant speaks — instant differentiation.
---
## Architecture
```
MCP client (Claude Desktop / Code)
│ stdio (MCP protocol)
▼
┌──────────────────────────────┐
│ FastMCP server (server.py) │ tools: list_datasets, query_metric, top_n
│ every call wrapped by ───┐ │
│ UsageTracker.track() │ │
└────────────┬───────────────┘ │
▼ ▼
data.py (query engine) usage.py (SQLite: tool, latency, ok/err)
synthetic 'orders' │
dataset (or your DW) └──► stats(): calls / error-rate / latency per tool
```
The tool logic (`tools.py` / `data.py`) is deliberately decoupled from the MCP SDK so it's unit-testable and you could expose the same functions over REST or a CLI. In production, point `data.py` at your warehouse — or at **MetricForge** for governed metrics.
| Module | Responsibility |
|--------|----------------|
| `data.py` | Deterministic synthetic dataset + aggregation queries |
| `tools.py` | SDK-independent tool registry + `call_tool()` |
| `usage.py` | `UsageTracker` — records every call, computes per-tool stats |
| `server.py` | FastMCP server wiring tools + usage tracking |
| `cli.py` | `serve`, `tools`, `demo` |
---
## Tech stack
**Python 3.10+ · `mcp` SDK (FastMCP) 1.x · SQLite · Typer + Rich · pytest · Docker**
---
## Quickstart
```bash
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt && pip install -e .
mcpantry tools # list exposed tools
mcpantry demo # call tools offline + show usage analytics
mcpantry serve # run as an MCP stdio server
```
### Register with Claude Desktop / Claude Code
Add to your MCP client config (see `claude_desktop_config.example.json`):
```json
{ "mcpServers": { "mcpantry": { "command": "mcpantry", "args": ["serve"] } } }
```
Then ask your assistant: *"Using mcpantry, what are the top 3 regions by revenue?"*
---
## Screenshots
> Real captures of live output. Regenerate anytime with `python scripts/make_screenshots.py` (renders the actual Rich tables to SVG — no mockups).
**Tools exposed over MCP** — what an agent discovers when it connects:
**A tool call result** — what the agent receives back from `top_n`:
**Usage analytics** — the observability layer: per-tool call volume, errors, and latency (including a forced error to show error-rate tracking):
> 💡 See the [live agent capture](#see-it-work--claude-calling-these-tools-live) at the top for end-to-end proof of a real AI agent calling these tools. For an even richer visual, register the server in **Claude Desktop** (GUI) via `claude_desktop_config.example.json` and screenshot the chat.
---
## MVP vs. Advanced
**MVP (this repo):** working FastMCP server with 3 analytics tools, SDK-independent + tested tool layer, SQLite usage analytics (calls/latency/errors), CLI, Docker, client config example.
**Advanced roadmap:**
- MCP **resources** & **prompts** (not just tools); auth + per-client scoping.
- Real warehouse backend; wire tools to **MetricForge** for governed metrics.
- Usage analytics dashboard + anomaly alerts (spike in a tool's error rate).
- Rate limiting / cost guards per tool; audit log of agent actions.
- Multi-server registry view across many MCP servers.
## Testing
```bash
pytest -q # 7 tests: query engine, day-range filtering, usage tracking (incl. errors), server wiring
```
## Resume bullets
- *Built **MCPantry**, a production Model Context Protocol server (FastMCP) that exposes governed analytics tools to AI agents, with a **usage-analytics layer** tracking per-tool call volume, latency, and error rate — MCP observability that doesn't exist off-the-shelf.*
- *Decoupled tool logic from the MCP transport for a fully unit-tested tool registry (7 tests), and shipped a Claude Desktop/Code integration config.*
## Why a recruiter cares
Shipping a real MCP server in 2026 signals you're at the frontier of agentic AI — it's literally the protocol assistants use to reach tools and data. Adding observability shows product maturity beyond a toy. Composes with **MetricForge** (data source), **PromptLedger**, and **EvalForge** to present a coherent "AI platform" portfolio.
## License
MIT
