Llm Pricing MCP Server

LLM Pricing MCP Server

Most LLM pricing tools are a static lookup table. This one checks its own numbers against a live, independently-maintained price registry and tells you when they disagree, routes to a model by cost and quality instead of just quoting a price, and tracks what you actually spent — not just what you might. All of that is backed by a RESTful API (FastAPI), 29 MCP tools over STDIO and HTTP, a conversational Agent + RAG pipeline, browser-based UIs, and a self-serve billing dashboard, for pricing data from 26 major LLM providers.

Live at: https://llm-pricing-api.fly.dev

---

Why this one

• Prices you can verify, not just trust — check_price_drift and get_data_quality compare every curated price against a live external registry and withhold (never silently serve) anything that's drifted more than 5%, with a single confirmed_pct trust score for the whole catalogue.
• Routes, doesn't just quote — recommend_model and optimize_workload pick a model by cost and quality for your actual task, flagging it when a cheaper pick trades away quality rather than silently recommending it.
• Tracks what you spent, not just what you might — record_usage, analyze_session_usage, and import_session_usage record and analyze real spend, including backfilling a coding-agent session that wasn't instrumented to track usage live.
• More than an MCP server — the same pricing engine also powers a REST API, browser UIs (calculator, side-by-side comparison, history/trends), and a self-serve billing dashboard.

---

Features

MCP Interface (STDIO + HTTP)

• 29 MCP Tools: get_all_pricing, estimate_cost, compare_costs, predict_cost, optimize_workload, recommend_model, check_price_drift, get_data_quality, get_performance_metrics, get_use_cases, get_ide_pricing, get_telemetry, get_pricing_history, get_pricing_trends, register_price_alert, list_price_alerts, delete_price_alert, get_pricing_export_url, list_conversations, delete_conversation, ask_agent, record_usage, get_usage_summary, register_budget_alert, list_budget_alerts, delete_budget_alert, get_cache_stats, analyze_session_usage, import_session_usage
• STDIO transport — JSON-RPC 2.0 over STDIO for local Claude Desktop integration
• HTTP transport — POST /mcp (JSON-RPC 2.0 over HTTP) for remote MCP clients — no local install needed
• MCP Protocol version: 2024-11-05

RESTful API

• Real-time pricing from 26 providers (150+ models), async fetching with smart caching
• Cost estimation: single model (POST /cost-estimate) and batch comparison (POST /cost-estimate/batch)
• Performance metrics, use-case recommendations, pricing history, trends
• Router recommendation (POST /router/recommend) with feedback loop; GET /cache-stats reports process-lifetime hit/miss stats for its ~5-minute recommendation cache
• Actual usage/spend tracking (POST /usage, GET /usage/summary) — the real-cost counterpart to /cost-estimate; tag events with session_id and analyze one session on demand (GET /usage/session/{session_id}) for a grounded recommendation with estimated savings
• OpenAI-compatible proxy (POST /v1/chat/completions) for drop-in SDK integration
• Webhook alerts for price changes and budget-spend thresholds (POST /usage/alerts, HMAC-SHA256 signed)
• Interactive docs: /docs (Swagger) and /redoc

Repo Cost Auditor (scripts/audit_repo.py)

• Statically scans a Python codebase for LLM SDK call sites (OpenAI, Anthropic, Google, LangChain), no credentials or network calls to your code required
• Estimates per-call-site cost using the same pricing data and token math as predict_cost
• Recommends cheaper models, prompt caching, Batch API (for calls in a loop or an offline-looking path), and task-based right-sizing (flagship model on a simple task) — plus flags the same prompt duplicated across call sites — see python scripts/audit_repo.py --help
• Static estimates only (assumes a configurable calls/month) — pair with POST /usage's actual recorded spend once deployed for real numbers

AI-Native SDLC Pipeline (/release-feature, for contributors using Claude Code)

• Runs a feature request through dedicated phase agents instead of one agent doing everything at once: Spec → Design → Code → Review → Test & Release
• Spec fixes what the feature does (requirements, acceptance criteria, non-goals) with zero implementation detail; Design fixes how it's built (approach, version bump, branch name) given a fixed Spec — neither phase re-derives the other's decision
• Review fans out to three parallel agents (correctness, security, simplification) over the diff; Test & Release checks the result against the Spec's acceptance criteria, triages Review's findings, runs this repo's full release checklist, and is the only phase that commits, pushes, and opens the PR
• Defined in .claude/agents/phase-*.md (five phase agents) and .claude/workflows/release-feature.js (the Code→Review→Test orchestrator) — see CLAUDE.md's "AI-Native SDLC Pipeline" section
• Ends at an open PR against develop; merging is still a human decision

Agent + RAG Pipeline

• Configurable LLM backend: OpenAI GPT-4o-mini (default) or Anthropic Claude via env vars
• ReAct loop agent with access to 26 of the 29 MCP tools (excludes ask_agent, get_telemetry, and get_cache_stats)
• TF-IDF RAG over pricing docs with top-k retrieval
• Conversation memory: per-session SQLite persistence, configurable turn limit
• Chat UI at /chat — streams ReAct progress in real time
• POST /agent/chat — blocking JSON response
• POST /agent/chat/stream — SSE stream (thinking / tool_call / tool_result / answer / done)

Browser UIs

All UIs share a consistent dark design system (CSS variables, 'Segoe UI' font, #0f1117 background, #7c6af7 accent) and are fully mobile-responsive with a sticky hamburger navigation bar.

SaaS Billing (Stripe)

• Free tier signup: POST /billing/signup (email → API key, no Stripe required)
• Paid tiers (Pro/Enterprise) via Stripe Checkout → auto-updates rate limits
• Self-serve portal: GET /billing/portal
• Usage dashboard: GET /billing/me (router calls, savings, acceptance rate)
• Stripe webhook handler: POST /billing/webhook

API Key Tiers & Rate Limiting

• Free: 30 req/min · Pro: 120 req/min · Enterprise: 600 req/min
• Tier comes from the billing DB (customer API key), or from the X-Api-Key-Tier header only when the request also carries the valid global MCP_API_KEY — anonymous requests always get the default bucket, so the header can't be used to self-select a higher limit
• GET /rate-limits/tiers — public endpoint listing tier details

Security & Quality

• Most endpoints are public (read-only pricing data, UIs, MCP tools)
• Protected endpoints (/billing/me, /router/recommend, /router/feedback, /billing/portal) require a billing API key or the global MCP_API_KEY
• Rate limiting per client IP + tier bucket — includes the anonymous /agent/chat and /agent/chat/stream endpoints (no API key needed, but throttled, since each call runs an LLM on the operator's key)
• Request size limit (1MB default)
• 1224 passing tests, CI/CD on every PR (test → lint → bandit → OSV → gitleaks → deploy)

Deployment

• Primary: Fly.io — shared-cpu-1x, 512MB, ~$3.40/mo
• CI/CD: GitHub Actions — test → deploy on master push
• Blue-green deployment support, graceful shutdown (SIGTERM/SIGINT)
• Health probes: /health, /health/live, /health/ready, /health/detailed

---

Table of Contents

• Quick Start (Claude Desktop)
• Quick Start (API)
• HTTP MCP Transport
• API Reference
• Configuration
• Development
• Testing
• Deployment
• Contributing
• Roadmap

---

Quick Start (Claude Desktop)

One-click links above open Cursor/VS Code directly (best-effort — deep-link support varies by client version). Every other client uses the copy-paste config below, which always works.

Option A — Remote (no install needed)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "llm-pricing": {
      "url": "https://llm-pricing-api.fly.dev/mcp"
    }
  }
}

Restart Claude Desktop. All 29 pricing tools are immediately available.

Option B — STDIO via npx (no clone, no Python)

For clients that only support command-based STDIO servers (no direct remote/HTTP config support). This runs a zero-dependency npm package that bridges stdin/stdout to the hosted server above — nothing to clone, no Python or pip install needed.

{
  "mcpServers": {
    "llm-pricing": {
      "command": "npx",
      "args": ["-y", "llm-pricing-mcp"]
    }
  }
}

Restart Claude Desktop. See npm/llm-pricing-mcp/README.md for configuration options (self-hosting, timeouts).

Option C — Local STDIO, fully offline

1. Clone and install:

git clone https://github.com/skakumanu/llm-pricing-mcp-server.git
cd llm-pricing-mcp-server
python -m venv .venv && source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

1. Add to claude_desktop_config.json:

{
  "mcpServers": {
    "llm-pricing": {
      "command": "python",
      "args": ["/absolute/path/to/mcp/server.py"],
      "cwd": "/absolute/path/to/llm-pricing-mcp-server",
      "env": { "PYTHONUNBUFFERED": "1" }
    }
  }
}

See docs/CLAUDE_INTEGRATION.md for detailed setup, Windows paths, and troubleshooting.

---

Quick Start (API)

Running the Server

python src/main.py
# or
uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

Public Endpoints (no auth)

# Get all pricing
curl http://localhost:8000/pricing

# Estimate cost
curl -X POST http://localhost:8000/cost-estimate \
  -H "Content-Type: application/json" \
  -d '{"model_name": "gpt-4o", "input_tokens": 1000, "output_tokens": 500}'

# Chat with the agent
curl -X POST http://localhost:8000/agent/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "What is the cheapest model for RAG pipelines?"}'

# OpenAI-compatible routing proxy
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "messages": [{"role": "user", "content": "hi"}]}'

Protected Endpoints (billing API key or MCP_API_KEY)

# Get your API key via free signup
curl -X POST http://localhost:8000/billing/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

# Use the returned api_key for protected endpoints
curl -H "x-api-key: <your-api-key>" \
  http://localhost:8000/billing/me

curl -X POST http://localhost:8000/router/recommend \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"max_cost_per_1m_tokens": 5}'

Agent Streaming

curl -X POST http://localhost:8000/agent/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"message": "Compare GPT-4o vs Claude Sonnet pricing"}' \
  --no-buffer

Events: thinking → tool_call → tool_result → answer → done

---

HTTP MCP Transport

The server exposes a JSON-RPC 2.0 endpoint at POST /mcp supporting the MCP protocol over HTTP (protocol version 2024-11-05).

Supported methods

Example

# List tools
curl -X POST https://llm-pricing-api.fly.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Call a tool
curl -X POST https://llm-pricing-api.fly.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 2, "method": "tools/call",
    "params": {
      "name": "estimate_cost",
      "arguments": {"model_name": "gpt-4o", "input_tokens": 1000, "output_tokens": 500}
    }
  }'

GET /mcp returns server info and a config snippet. Full interactive docs at /docs (Swagger UI) and /redoc.

---

API Reference

Public Endpoints

Protected Endpoints (billing API key or MCP_API_KEY)

Key Request/Response Examples

POST /cost-estimate

// Request
{"model_name": "gpt-4o", "input_tokens": 1000, "output_tokens": 500}

// Response
{
  "model_name": "gpt-4o", "provider": "OpenAI",
  "input_tokens": 1000, "output_tokens": 500,
  "input_cost": 0.0000025, "output_cost": 0.000005,
  "total_cost": 0.0000075, "currency": "USD"
}

POST /billing/signup

// Request
{"email": "you@example.com"}

// Response
{
  "api_key": "abc123...", "org_id": "org-xyz...",
  "tier": "free", "message": "Welcome! Your free API key is ready."
}

POST /router/recommend

// Request (x-api-key header required)
{"max_cost_per_1m_tokens": 5, "task_type": "code"}

// Response
{
  "recommended": {"model_name": "gpt-4o-mini", "provider": "OpenAI", ...},
  "alternatives": [...],
  "reason": "Best quality/cost ratio for code tasks under $5/1M tokens",
  "routing_id": "uuid4..."
}

---

Configuration

Environment Variables

# LLM Backend (Agent)
AGENT_LLM_PROVIDER=openai           # "openai" (default) or "anthropic"
AGENT_MODEL=gpt-4o-mini             # Model name
OPENAI_API_KEY=sk-...               # Required when AGENT_LLM_PROVIDER=openai
ANTHROPIC_API_KEY=sk-ant-...        # Required when AGENT_LLM_PROVIDER=anthropic

# Server
SERVER_HOST=0.0.0.0
SERVER_PORT=8000
DEBUG=false

# Security
MCP_API_KEY=your-strong-random-key  # Global admin key (optional — billing keys work too)
RATE_LIMIT_PER_MINUTE=60            # Default rate limit (overridden by tier)

# Billing (Stripe)
STRIPE_SECRET_KEY=sk_live_...       # Optional — free signup works without this
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_ID_PRO=price_...
STRIPE_PRICE_ID_ENTERPRISE=price_...
BILLING_DB_PATH=/app/data/billing.db
BILLING_BASE_URL=https://llm-pricing-api.fly.dev

Switching LLM providers requires only env var changes — no code modifications:

---

Development

Project Structure

llm-pricing-mcp-server/
├── src/
│   ├── __init__.py                  # Version (1.48.0)
│   ├── main.py                      # FastAPI app + all endpoints
│   ├── config/settings.py           # Pydantic settings
│   ├── models/                      # Pydantic models (pricing, billing, router, …)
│   └── services/                    # Business logic
│       ├── pricing_aggregator.py    # Multi-provider pricing aggregator
│       ├── billing_service.py       # SQLite billing / customer DB
│       ├── router.py                # Model routing engine
│       ├── savings_tracker.py       # Router savings analytics
│       ├── benchmark_service.py     # Quality scores + HF API
│       ├── pricing_history.py       # Historical snapshot DB
│       └── …
├── mcp/
│   ├── server.py                    # STDIO JSON-RPC 2.0 server
│   └── tools/                       # 29 MCP tool implementations
│       ├── tool_manager.py
│       ├── get_all_pricing.py
│       ├── estimate_cost.py
│       └── …
├── agent/
│   ├── pricing_agent.py             # ReAct loop agent
│   ├── llm_backend.py               # OpenAI + Anthropic backends
│   └── tools.py                     # Agent tool wrappers
├── static/                          # Browser UIs (one dir per page)
│   ├── landing/                     # / (marketing page)
│   ├── chat/                        # /chat (agent UI)
│   ├── calculator/                  # /calculator
│   ├── compare/                     # /compare
│   ├── history/                     # /history
│   ├── trends/                      # /trends
│   ├── widget/                      # /widget
│   ├── billing/                     # /billing
│   └── admin/                       # /admin
├── tests/                           # 667 tests
├── docs/                            # Extended documentation
├── .github/workflows/ci-cd.yml      # CI/CD pipeline
├── Dockerfile
├── fly.toml                         # Fly.io deployment config
└── requirements.txt

Adding a New Provider

1. Create src/services/<provider>_pricing.py implementing BasePricingProvider
2. Register in src/services/pricing_aggregator.py
3. Add env var for optional API key in src/config/settings.py
4. Add tests in tests/

---

Testing

# Run all 667 tests
pytest

# With coverage
pytest --cov=src --cov-report=term-missing

# Specific suites
pytest tests/test_api.py -v
pytest tests/test_billing_endpoints.py -v
pytest tests/test_mcp_http.py -v     # HTTP MCP transport
pytest tests/test_router.py -v

Test Files

---

Deployment

Fly.io (Primary)

The app is deployed on Fly.io and auto-deploys on every push to master.

# Install flyctl
# https://fly.io/docs/getting-started/installing-flyctl/

# Deploy manually
flyctl deploy

# Set secrets
flyctl secrets set \
  MCP_API_KEY=... \
  OPENAI_API_KEY=... \
  AGENT_LLM_PROVIDER=openai \
  AGENT_MODEL=gpt-4o-mini

# Set Stripe secrets (optional — free tier works without)
flyctl secrets set \
  STRIPE_SECRET_KEY=sk_live_... \
  STRIPE_WEBHOOK_SECRET=whsec_... \
  STRIPE_PRICE_ID_PRO=price_... \
  STRIPE_PRICE_ID_ENTERPRISE=price_... \
  BILLING_BASE_URL=https://llm-pricing-api.fly.dev

Configuration in fly.toml. Persistent volume at /app/data/ stores all SQLite databases.

GitHub Actions CI/CD

The .github/workflows/ci-cd.yml pipeline:

1. Runs all 667 tests on every PR
2. Deploys to Fly.io on master push (via FLY_API_TOKEN secret)
3. Performs a health check after deploy

Health Check Endpoints

GET /health        → {"status":"healthy","version":"1.39.0"}
GET /health/live   → {"alive":true}
GET /health/ready  → {"ready":true,"checks":{...}}
GET /health/detailed → detailed environment + service statuses

Blue-Green Deployment

Graceful shutdown with request draining is supported. See docs/BLUE_GREEN_DEPLOYMENT.md.

---

Live Data

The server fetches pricing data from official public pricing pages using web scraping with smart caching. No provider API keys are required for pricing data.

• Cache TTL: 2 hours for pricing, 5 minutes for performance metrics
• Fallback: Static hardcoded data if live sources are unavailable
• Providers: OpenAI, Anthropic, Google, Cohere, Mistral AI, Groq, Together AI, Fireworks AI, Perplexity AI, AI21 Labs, Anyscale, Amazon Bedrock

Optional provider API keys (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.) improve model-list freshness but are not required.

---

Contributing

See docs/CONTRIBUTING.md. This repo uses Git Flow:

feature/<name>  →  develop (PR)  →  master (PR)  →  Fly.io auto-deploy

• Never commit directly to develop or master
• Branch names: feature/<topic>-v<version> (e.g. feature/stripe-billing-v1.37.0)
• Open PRs against develop; maintainers promote develop → master for releases

---

License

MIT — see LICENSE.

---

Roadmap

Completed

• v1.39.0 — OpenAPI tags + grouped Swagger UI; 15th MCP tool (ask_agent)
• v1.38.6 — MCP server fixes: initialize all services, register ask_agent tool, init PricingAlertService
• v1.38.5 — Landing page MCP integration guide (Claude Desktop, VS Code, Cursor)
• v1.38.4 — Billing beta UX: coming-soon copy, disabled paid buttons, graceful 503
• v1.38.3 — Dark theme + shared nav for chat and conversations pages
• v1.38.2 — Design system standardized across all 9 UIs (admin as canonical reference)
• v1.38.1 — UI theme consistency pass
• v1.38.0 — HTTP MCP transport (POST /mcp, GET /mcp) for remote clients
• v1.37.3 — Mobile-responsive UI, consistent nav across all pages
• v1.37.2 — SQLite directory auto-creation on Fly.io volume mount
• v1.37.1 — Marketing landing page at /
• v1.37.0 — Stripe SaaS billing: free signup, Pro/Enterprise tiers, self-serve portal
• v1.36.0 — API key tiers (free/pro/enterprise), router feedback loop, streaming router, Fly.io migration
• v1.35.0 — Quality value index, benchmark service, model router, savings tracker
• v1.33.0 — Switched default LLM backend to GPT-4o-mini (~20× cheaper)
• v1.27.0–v1.32.0 — Admin dashboard, widget, compare UI, calculator, price alerts, history export
• v1.10.0–v1.26.0 — Agent + RAG pipeline, streaming, conversation memory, pricing history
• v1.5.1 — 12 providers, 87+ models, live data fetching
• v1.6.0 — Full MCP protocol (STDIO JSON-RPC 2.0), Claude Desktop integration

Upcoming

• Stripe products live setup (configure products + set Fly.io secrets)
• Shut down Azure App Service (currently running in parallel at ~$27/mo)
• Custom domain
• Additional LLM backends (Groq direct, Ollama local)
• WebSocket support for live price subscriptions