{ "markdown": "# Metrx MCP Server\n\n\n\n[![npm version](https://img.shields.io/npm/v/@metrxbot/mcp-server)](https://www.npmjs.com/package/@metrxbot/mcp-server)\n[![CI](https://github.com/metrxbots/mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/metrxbots/mcp-server/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Smithery](https://smithery.ai/badge/@metrxbot/mcp-server)](https://smithery.ai/server/metrxbot/mcp-server)\n[![Glama](https://glama.ai/mcp/servers/metrxbots/metrx-mcp-server/badge)](https://glama.ai/mcp/servers/metrxbots/metrx-mcp-server)\n\n**Your AI agents are wasting money.** Metrx finds out how much, and fixes it.\n\nThe official [MCP server](https://modelcontextprotocol.io) for [Metrx](https://metrxbot.com) — the AI Agent Cost Intelligence Platform. Give any MCP-compatible agent (Claude, GPT, Gemini, Cursor, Windsurf) the ability to track its own costs, detect waste, optimize model selection, and prove ROI.\n\n\n \"Metrx\n\n\n## Why Metrx?\n\n| Problem | What Metrx Does |\n|---------|-----------------|\n| No visibility into agent spend | Real-time cost dashboards per agent, model, and provider |\n| Overpaying for LLM calls | Provider arbitrage finds cheaper models for the same task |\n| Runaway costs | Budget enforcement with auto-pause when limits are hit |\n| Wasted tokens | Cost leak scanner detects retry storms, context bloat, model mismatch |\n| Can't prove AI ROI | Revenue attribution links agent actions to business outcomes |\n\n## Quick Start\n\n### Try it now — no signup required\n\n```bash\nnpx @metrxbot/mcp-server --demo\n```\n\nThis starts the server with sample data so you can explore all 23 tools instantly.\n\n### Connect your real data\n\n**Option A — Interactive login (recommended):**\n\n```bash\nnpx @metrxbot/mcp-server --auth\n```\n\nOpens your browser to get an API key, validates it, and saves it to `~/.metrxrc` so you never need to set env vars.\n\n**Option B — Environment variable:**\n\n```bash\nMETRX_API_KEY=sk_live_your_key_here npx @metrxbot/mcp-server --test\n```\n\nGet your free API key at [app.metrxbot.com/sign-up](https://app.metrxbot.com/sign-up).\n\n### Add to your MCP client (Claude Desktop, Cursor, Windsurf)\n\nIf you used `--auth`, no `env` block is needed — the key is read from `~/.metrxrc` automatically:\n\n```json\n{\n \"mcpServers\": {\n \"metrx\": {\n \"command\": \"npx\",\n \"args\": [\"@metrxbot/mcp-server\"]\n }\n }\n}\n```\n\nOr pass the key explicitly via environment:\n\n```json\n{\n \"mcpServers\": {\n \"metrx\": {\n \"command\": \"npx\",\n \"args\": [\"@metrxbot/mcp-server\"],\n \"env\": {\n \"METRX_API_KEY\": \"sk_live_your_key_here\"\n }\n }\n }\n}\n```\n\n### Remote HTTP endpoint\n\nFor remote agents (no local install needed):\n\n```\nPOST https://metrxbot.com/api/mcp\nAuthorization: Bearer sk_live_your_key_here\nContent-Type: application/json\n```\n\n### From npm\n\n```bash\nnpm install @metrxbot/mcp-server\n```\n\n## 23 Tools Across 10 Domains\n\n### Dashboard (3 tools)\n| Tool | Description |\n|------|-------------|\n| `metrx_get_cost_summary` | Comprehensive cost summary — total spend, call counts, error rates, and optimization opportunities |\n| `metrx_list_agents` | List all agents with status, category, cost metrics, and health indicators |\n| `metrx_get_agent_detail` | Detailed agent info including model, framework, cost breakdown, and performance history |\n\n### Optimization (4 tools)\n| Tool | Description |\n|------|-------------|\n| `metrx_get_optimization_recommendations` | AI-powered cost optimization recommendations per agent or fleet-wide |\n| `metrx_apply_optimization` | One-click apply an optimization recommendation to an agent |\n| `metrx_route_model` | Model routing recommendation for a specific task based on complexity |\n| `metrx_compare_models` | Compare LLM model pricing and capabilities across providers |\n\n### Budgets (3 tools)\n| Tool | Description |\n|------|-------------|\n| `metrx_get_budget_status` | Current status of all budget configurations with spend vs. limits |\n| `metrx_set_budget` | Create or update a budget with hard, soft, or monitor enforcement |\n| `metrx_update_budget_mode` | Change enforcement mode of an existing budget or pause/resume it |\n\n### Alerts (3 tools)\n| Tool | Description |\n|------|-------------|\n| `metrx_get_alerts` | Active alerts and notifications for your agent fleet |\n| `metrx_acknowledge_alert` | Mark one or more alerts as read/acknowledged |\n| `metrx_get_failure_predictions` | Predictive failure analysis — identify agents likely to fail before it happens |\n\n### Experiments (3 tools)\n| Tool | Description |\n|------|-------------|\n| `metrx_create_model_experiment` | Start an A/B test comparing two LLM models with traffic splitting |\n| `metrx_get_experiment_results` | Statistical significance, cost delta, and recommended action |\n| `metrx_stop_experiment` | Stop a running model routing experiment and lock in the winner |\n\n### Cost Leak Detector (1 tool)\n| Tool | Description |\n|------|-------------|\n| `metrx_run_cost_leak_scan` | Comprehensive 7-check cost leak audit across your entire agent fleet |\n\n### Attribution (3 tools)\n| Tool | Description |\n|------|-------------|\n| `metrx_attribute_task` | Link agent actions to business outcomes for ROI tracking |\n| `metrx_get_task_roi` | Calculate return on investment for an agent — costs vs. attributed outcomes |\n| `metrx_get_attribution_report` | Multi-source attribution report with confidence scores and top contributors |\n\n### Alert Configuration (1 tool)\n| Tool | Description |\n|------|-------------|\n| `metrx_configure_alert_threshold` | Set cost or operational alert thresholds with email, webhook, or auto-pause |\n\n### ROI Audit (1 tool)\n| Tool | Description |\n|------|-------------|\n| `metrx_generate_roi_audit` | Board-ready ROI audit report for your AI agent fleet |\n\n### Upgrade Justification (1 tool)\n| Tool | Description |\n|------|-------------|\n| `metrx_get_upgrade_justification` | ROI report for tier upgrades based on current usage patterns |\n\n## Prompts\n\nPre-built prompt templates for common workflows:\n\n| Prompt | Description |\n|--------|-------------|\n| `analyze-costs` | Comprehensive cost overview — spend breakdown, top agents, optimization opportunities |\n| `find-savings` | Discover optimization opportunities — model downgrades, caching, routing |\n| `cost-leak-scan` | Scan for waste patterns — retry storms, oversized contexts, model mismatch |\n\n## Examples\n\n### \"How much am I spending?\"\n\n```\nUser: What was my AI cost this week?\n→ metrx_get_cost_summary(period_days=7)\n\nTotal Spend: $234.56 | Calls: 2,450 | Error Rate: 0.2%\n├── customer-support: $156.23 (1,800 calls)\n└── code-generator: $78.33 (650 calls)\n\n💡 Switch customer-support from GPT-4 to Claude Sonnet: Save $42/week\n```\n\n### \"Find me savings\"\n\n```\nUser: Am I overpaying for my agents?\n→ metrx_compare_models(models=[\"gpt-4o\", \"claude-3-5-sonnet\", \"gemini-1.5-pro\"])\n\nModel Comparison (per 1M tokens):\n├── gpt-4o: $2.50 in / $10.00 out\n├── claude-3-5-sonnet: $3.00 in / $15.00 out\n└── gemini-1.5-pro: $3.50 in / $10.50 out\n```\n\n### \"Test a cheaper model\"\n\n```\nUser: Test Claude 3.5 Sonnet against my GPT-4 setup\n→ metrx_create_model_experiment(agent_id=\"agent_123\",\n model_a=\"gpt-4o\", model_b=\"claude-3-5-sonnet-20241022\", traffic_split=10)\n\nExperiment started: 90% GPT-4o, 10% Claude 3.5 Sonnet\nCheck back in 14 days for statistical significance.\n```\n\n## Companion Tool: Cost Leak Detector\n\nThis repo also includes [`@metrxbot/cost-leak-detector`](./packages/cost-leak-detector) — a free, offline CLI that scans your LLM API logs for wasted spend. No signup, no cloud, no data leaves your machine.\n\n```bash\nnpx @metrxbot/cost-leak-detector demo\n```\n\nIt runs 7 checks (idle agents, premium model overuse, missing caching, high error rates, context overflow, no budgets, arbitrage opportunities) and gives you a scored report in seconds. See the [full docs](./packages/cost-leak-detector/README.md).\n\n## Configuration\n\n### API Key (required)\n\nThe server looks for your API key in this order:\n\n1. `METRX_API_KEY` environment variable\n2. `~/.metrxrc` file (created by `--auth`)\n\nRun `npx @metrxbot/mcp-server --auth` to save your key, or set the env var directly.\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `METRX_API_KEY` | Yes* | Your Metrx API key ([get one free](https://app.metrxbot.com/sign-up)) |\n| `METRX_API_URL` | No | Override API base URL (default: `https://metrxbot.com/api/v1`) |\n\n*Not required if you've run `--auth` — the key is read from `~/.metrxrc` automatically.\n\n### CLI Flags\n\n| Flag | Description |\n|------|-------------|\n| `--demo` | Start with sample data — no API key or signup needed |\n| `--auth` | Interactive login — opens browser, validates key, saves to `~/.metrxrc` |\n| `--test` | Verify your API key and connection |\n\n## Rate Limiting\n\n60 requests per minute per tool. For higher limits, contact support@metrxbot.com.\n\n## Development\n\n```bash\ngit clone https://github.com/metrxbots/mcp-server.git\ncd mcp-server\nnpm install\nnpm run typecheck\nnpm test\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.\n\n## Links\n\n- **Website**: [metrxbot.com](https://metrxbot.com)\n- **Docs**: [docs.metrxbot.com](https://docs.metrxbot.com)\n- **npm**: [@metrxbot/mcp-server](https://www.npmjs.com/package/@metrxbot/mcp-server)\n- **Smithery**: [metrxbot/mcp-server](https://smithery.ai/server/metrxbot/mcp-server)\n- **Support**: support@metrxbot.com\n\n## A Note on Naming\n\nThe product is **Metrx** (metrxbot.com). The npm scope is `@metrxbot` and the Smithery listing is `metrxbot/mcp-server`. The GitHub organization is `metrxbots` (with an **s**) because `metrxbot` was already taken on GitHub. If you see `metrxbot` vs `metrxbots` across platforms, they're the same project — just a GitHub namespace constraint.\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n\n\n## 💬 Feedback\n\nDid Metrx work for you? We'd love to hear it — good or bad.\n\n- **GitHub Discussions**: [Start a thread](https://github.com/metrxbots/mcp-server/discussions) — questions, ideas, what you're building\n- **Bug reports**: [Open an issue](https://github.com/metrxbots/mcp-server/issues)\n- **Quick feedback**: Drop a comment on our [Product Hunt listing](https://www.producthunt.com/products/metrx)\n\nIf you installed but hit a snag, tell us what happened — we read every report.\n", "bytes": 10617, "sha": "2e310e79be00040623b9bb81011b42fa4b528b56983baa0a7d9d9b314401c8f2", "repo_slug": "metrxbots/mcp-server", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_metrxbots_mcp_server_200a2dbd/readme" }