What can you do with this server?

The Metrx MCP Server is an AI Agent Cost Intelligence Platform that enables MCP-compatible AI agents to track, optimize, and govern LLM costs and ROI across their agent fleet. Cost Visibility & Dashboards * Get comprehensive cost summaries (total spend, call counts, error rates) for up to 90 days * List all agents with status, category, and cost metrics * Drill into per-agent details including model, framework, and performance history Cost Optimization * Receive AI-powered recommendations (model switching, token guardrails, provider arbitrage, batch processing) * Apply one-click optimization fixes to individual agents * Get model routing recommendations based on task complexity * Compare LLM pricing and capabilities across providers (OpenAI, Anthropic, Google, etc.) Budget Management * Monitor budget status and spending vs. limits across your fleet * Create or update budgets with daily/monthly periods and enforcement modes (alert-only, soft block, hard block) * Pause, resume, or change enforcement modes on existing budgets Alerts & Predictions * Retrieve active alerts for cost spikes, error rates, and budget warnings (filterable by severity) * Acknowledge or dismiss alerts * Get predictive failure analysis identifying agents at risk before issues occur * Configure automated alert thresholds triggering email, webhook, or auto-pause actions A/B Model Experiments * Run A/B tests comparing two LLM models with configurable traffic splitting * Monitor results including statistical significance, cost delta, and current winner * Stop experiments and optionally promote the winning model Cost Leak Detection * Run a 7-check audit identifying inefficiencies: idle agents, model overprovisioning, missing caching, high error rates, context bloat, missing budgets, and cross-provider arbitrage opportunities * Output as human-readable markdown or machine-readable JSON for CI/CD pipelines ROI & Revenue Attribution * Link agent actions to business outcomes (revenue, cost savings, efficiency, quality) from sources like Stripe, HubSpot, Zendesk, etc. * Calculate per-agent ROI and generate multi-source attribution reports with confidence scores * Produce board-ready ROI audit reports for the full fleet Upgrade Justification * Generate ROI reports demonstrating potential savings from upgrading to higher service tiers

How do I use Metrx MCP Server?

This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions: * Metrxbot

Metrx MCP Server

by metrxbots

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

The Metrx MCP Server is an AI Agent Cost Intelligence Platform that enables MCP-compatible AI agents to track, optimize, and govern LLM costs and ROI across their agent fleet.

Cost Visibility & Dashboards

Get comprehensive cost summaries (total spend, call counts, error rates) for up to 90 days
List all agents with status, category, and cost metrics
Drill into per-agent details including model, framework, and performance history

Cost Optimization

Receive AI-powered recommendations (model switching, token guardrails, provider arbitrage, batch processing)
Apply one-click optimization fixes to individual agents
Get model routing recommendations based on task complexity
Compare LLM pricing and capabilities across providers (OpenAI, Anthropic, Google, etc.)

Budget Management

Monitor budget status and spending vs. limits across your fleet
Create or update budgets with daily/monthly periods and enforcement modes (alert-only, soft block, hard block)
Pause, resume, or change enforcement modes on existing budgets

Alerts & Predictions

Retrieve active alerts for cost spikes, error rates, and budget warnings (filterable by severity)
Acknowledge or dismiss alerts
Get predictive failure analysis identifying agents at risk before issues occur
Configure automated alert thresholds triggering email, webhook, or auto-pause actions

A/B Model Experiments

Run A/B tests comparing two LLM models with configurable traffic splitting
Monitor results including statistical significance, cost delta, and current winner
Stop experiments and optionally promote the winning model

Cost Leak Detection

Run a 7-check audit identifying inefficiencies: idle agents, model overprovisioning, missing caching, high error rates, context bloat, missing budgets, and cross-provider arbitrage opportunities
Output as human-readable markdown or machine-readable JSON for CI/CD pipelines

ROI & Revenue Attribution

Link agent actions to business outcomes (revenue, cost savings, efficiency, quality) from sources like Stripe, HubSpot, Zendesk, etc.
Calculate per-agent ROI and generate multi-source attribution reports with confidence scores
Produce board-ready ROI audit reports for the full fleet

Upgrade Justification

Generate ROI reports demonstrating potential savings from upgrading to higher service tiers

Metrx MCP Server

The Model Context Protocol (MCP) server for Metrx: how a company manages the AI agents it employs. Each agent gets a job contract, a scorecard against it, and a P&L: what it cost and what it produced. This server exposes those records as tools that any MCP-compatible client (Claude, GPT, Gemini, custom agents) can call. Version 0.5.0.

This package is the single source for both transports: the npm package you run locally over stdio, and the hosted server at https://metrxbot.com/api/mcp. The public repository at https://github.com/metrxbots/mcp-server is a mirror, synced from the monorepo by packages/mcp-server/scripts/publish-mirror.ts. Contributors open pull requests against the monorepo; issues go to https://github.com/metrxbots/mcp-server/issues.

Quick Start

Three ways in.

1. The demo, no key. The public desk tools answer on the Northwind sample organization, which is synthetic demo data.

npx @metrxbot/mcp-server --demo

2. Interactive login. Opens the browser, saves the key locally, then verifies it.

npx @metrxbot/mcp-server --auth
npx @metrxbot/mcp-server --test

3. A key in the environment.

METRX_API_KEY=sk_live_xxx npx @metrxbot/mcp-server

npx @metrxbot/mcp-server --setup-claude writes the server entry into the Claude Desktop, Cursor or VS Code config for you.

Related MCP server: Odoo MCP Server

Claude Code plugin

The desk plugin wraps the workforce tool set in five skills.

claude plugin marketplace add metrxbots/mcp-server && claude plugin install metrx-desk@metrxbots

Versions: this server is 0.5.0 (@metrxbot/mcp-server). The desk plugin (metrx-desk) and the TypeScript SDK (@metrxbot/sdk) are separate artefacts with their own version numbers and release schedules; each states its version in its own package.

Command	What it does	Needs a key
`/metrx-desk:sample-review`	The Northwind sample review (synthetic demo data), relayed with every figure's label	No
`/metrx-desk:draft-job-contract`	Draft a job contract for one agent from a template (support_triage, sdr_qualification, internal_assistant, coding_patch); owner is required; publishing is a separate admin-scope step	No
`/metrx-desk:check-vendor-bill`	Reconcile a per-resolution vendor bill against your own records: matched, disputed, unmatched, outside coverage, with the disputed amount	No
`/metrx-desk:connect-metrx`	Create a key at Settings → Security, set METRX_API_KEY, restart, read your first review	Creates one
`/metrx-desk:weekly-decisions`	Your decision queue; record expand, re_specify, combine or retire with a rationale	Yes (read; write to record)

The full walkthrough, including the labels every figure carries and the plain HTTP routes, is at https://docs.metrxbot.com/desk.

Tools

The tool registry is published at https://metrxbot.com/.well-known/agent-card.json: names, descriptions, domains, the public subset that answers without a key, and the named tool sets. That file is the authoritative list; this README does not repeat it. Every tool's description ends with the scope it needs (read, write or admin).

Tool names carry the metrx_ prefix. The desk's public tools are metrx_get_workforce_review, metrx_draft_job_contract and metrx_check_vendor_bill. Signed-in desk tools include metrx_get_decision_queue, metrx_record_decision, metrx_get_scorecard, metrx_get_job_contract and metrx_set_job_contract; cost reads such as metrx_get_cost_summary sit alongside them. A job contract is recorded, not enforced at runtime: publishing one blocks no spend or traffic.

Guided Prompts

MCP prompts are templates that walk a client through a multi-step workflow.

`analyze-costs`

Fetches the cost summary, lists agents, gets optimization recommendations and returns a prioritized breakdown.

Arguments:

period_days (string, optional): number of days to analyze (default: "30")

`find-savings`

Checks recommendations, runs the cost leak scan and explains each finding in dollars.

Arguments: none

`cost-leak-scan`

Runs the waste audit: retry storms, oversized contexts, model mismatch, missing caching, idle agents, missing budgets, arbitrage gaps.

Arguments:

agent_id (string, optional): scan one agent by UUID, or omit to scan all

Installation

From npm

npm install @metrxbot/mcp-server

Quick Test

Verify your API key and connection:

METRX_API_KEY=sk_live_xxx npx @metrxbot/mcp-server --test

Configuration

Environment Variables

METRX_API_KEY (optional for --demo, required otherwise): your Metrx API key. Create one at https://app.metrxbot.com/settings/security
METRX_API_URL (optional): override the API base URL (default: https://app.metrxbot.com/api)

Hosted transport

The same registry is served over streamable HTTP at https://metrxbot.com/api/mcp. Add ?set=workforce to select the desk tool set. The Authorization: Bearer sk_live_... header is optional: without it the public tools answer on the demo (synthetic demo data).

{
  "mcpServers": {
    "metrx": {
      "type": "http",
      "url": "https://metrxbot.com/api/mcp?set=workforce",
      "headers": { "Authorization": "Bearer sk_live_your_key_here" }
    }
  }
}

MCP Client Setup (stdio)

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "metrx": {
      "command": "npx",
      "args": ["@metrxbot/mcp-server"],
      "env": {
        "METRX_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "metrx": {
      "command": "npx",
      "args": ["@metrxbot/mcp-server"],
      "env": {
        "METRX_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "metrx": {
      "command": "npx",
      "args": ["@metrxbot/mcp-server"],
      "env": {
        "METRX_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Or run directly:

METRX_API_KEY=sk_live_xxx npx @metrxbot/mcp-server

Rate Limiting

The stdio server enforces per-tool-category rate limits:

Category	Limit
Dashboard & Agents	60 requests/minute
Metrics	30 requests/minute
Experiments	10 requests/minute
Budgets	10 requests/minute
Alerts	10 requests/minute
Attribution	10 requests/minute
Optimization	5 requests/minute
Cost Leak Scan	2 requests/5 minutes
Default (other)	30 requests/minute

The public desk routes are limited per address at 30 requests per minute; the limit rides in the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. Hitting a limit returns an error with the retry-after time in seconds.

For high-volume use, contact support@metrxbot.com.

Error Handling

Every refusal carries a class. Over MCP it is a JSON-RPC error with data.class, data.doc and data.user_message; over HTTP it is an RFC 9457 problem body with Retry-After on the retryable classes.

Class	JSON-RPC code	HTTP status	Doc
`auth_required`	-32001	401	https://docs.metrxbot.com/desk#errors-auth-required
`insufficient_scope`	-32002	403	https://docs.metrxbot.com/desk#errors-insufficient-scope
`rate_limited`	-32003	429	https://docs.metrxbot.com/desk#errors-rate-limited
`limiter_unavailable`	-32004	503	https://docs.metrxbot.com/desk#errors-limiter-unavailable
`demo_unavailable`	-32005	503	https://docs.metrxbot.com/desk#errors-demo-unavailable
`unknown_agent_key`	-32006	404	https://docs.metrxbot.com/desk#errors-unknown-agent-key
`invalid_params`	-32602	400	https://docs.metrxbot.com/desk#errors-invalid-params
`transport_error`	-32007	502	https://docs.metrxbot.com/desk#errors-transport-error

Server errors from the upstream API (500 and above) are retried with exponential backoff, up to 3 times.

Authentication

Requests to your own organization carry METRX_API_KEY in the Authorization header:

Authorization: Bearer sk_live_xxx

API keys are environment-scoped: sk_live_* for production, sk_test_* for testing, mk_* for machine keys.

Each key also carries scopes. Read tools need read; tools that change data need write; budget changes, publishing a job contract and creating an experiment need admin. An org owner or admin mints keys, including admin-scoped ones, in Settings → Security → API Keys.

Testing

Verify your API key:

METRX_API_KEY=sk_live_xxx npx @metrxbot/mcp-server --test

Run the test suite:

npm run test

Tests cover:

Protocol compliance (MCP spec validation)
Tool schema and input validation
API client retry logic and error handling
Rate limiting behavior
Output formatting

Troubleshooting

"METRX_API_KEY environment variable is required"

Set the key before starting the server, or run --demo for the public tools:

export METRX_API_KEY=sk_live_your_key
npx @metrxbot/mcp-server

Create a key at https://app.metrxbot.com/settings/security, or run npx @metrxbot/mcp-server --auth.

"Rate limit exceeded"

The error message includes a retry-after time in seconds. Your MCP client should retry after it. For production volume, contact support.

"401 Unauthorized" or `auth_required`

Your API key is invalid, expired or missing. Create a new one at https://app.metrxbot.com/settings/security.

`unknown_agent_key`

No agent in your organization has that agent_key. Check the Agents page in the dashboard; the error's suggestions lists close matches when there are any.

Support

Docs: https://docs.metrxbot.com (the desk: https://docs.metrxbot.com/desk)
API Status: https://status.metrxbot.com
Email: support@metrxbot.com
GitHub Issues: https://github.com/metrxbots/mcp-server/issues

License

MIT, see LICENSE.

Available Tools

41 tools

metrx_acknowledge_alertAcknowledge AlertA

Idempotent

Metrx MCP Server

Quick Start

Claude Code plugin

Tools

Guided Prompts

analyze-costs

find-savings

cost-leak-scan

Installation

From npm

Quick Test

Configuration

Environment Variables

Hosted transport

MCP Client Setup (stdio)

Claude Desktop

Cursor

Windsurf

Rate Limiting

Error Handling

Authentication

Testing

Troubleshooting

"METRX_API_KEY environment variable is required"

"Rate limit exceeded"

"401 Unauthorized" or auth_required

unknown_agent_key

Support

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

@intempt/mcp-serverofficial

Odoo MCP Server

Metabase MCP Plus

stessa-mcp

`analyze-costs`

`find-savings`

`cost-leak-scan`

"401 Unauthorized" or `auth_required`

`unknown_agent_key`