MCP Server

The Metrx MCP Server (@metrxbot/mcp-server) exposes 24 cost intelligence tools via the Model Context Protocol that any MCP-compatible AI agent — Claude, GPT, Gemini, or custom agents — can call to track costs, optimize models, manage budgets, and prove ROI.

Version: 0.2.2 · License: MIT · npm

Quick Start

1. Get an API key

2. Test the connection

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

3. Add to your MCP client

Claude Desktop (claude_desktop_config.json):

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

Cursor (.cursor/mcp.json):

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

Windsurf (~/.codeium/windsurf/mcp_config.json):

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

Environment Variables

Variable	Required	Description
`METRX_API_KEY`	Yes	Your Metrx API key (`sk_live_` or `sk_test_`)
`METRX_API_URL`	No	Override API base URL (default: `https://app.metrxbot.com/api`)

Tools Reference

All tools are prefixed with metrx_ in MCP (e.g., metrx_get_cost_summary).

Dashboard (3 tools)

`metrx_get_cost_summary`

Get a comprehensive cost summary for your AI agent fleet.

Parameter	Type	Default	Description
`days`	number (1–90)	30	Number of days to include

Returns total spend, call counts, error rates, agent breakdown, revenue attribution, and optimization opportunities.

`metrx_list_agents`

List all AI agents in your organization.

Parameter	Type	Default	Description
`status`	`active` \| `idle` \| `error` \| `archived`	—	Filter by status
`category`	string	—	Filter by category (e.g., “sales”, “support”)

`metrx_get_agent_detail`

Get detailed information about a specific agent.

Parameter	Type	Default	Description
`agent_id`	UUID	required	The agent UUID to look up

Optimization (4 tools)

`metrx_get_optimization_recommendations`

Get AI-powered cost optimization recommendations including model switching, token guardrails, provider arbitrage, and revenue intelligence insights.

Parameter	Type	Default	Description
`agent_id`	UUID	—	Specific agent to analyze (omit for fleet-wide)
`include_revenue`	boolean	true	Include revenue-side insights

`metrx_apply_optimization`

Apply a one-click optimization recommendation to an agent. Only works for suggestions marked as one_click: true.

Parameter	Type	Default	Description
`agent_id`	UUID	required	The agent to optimize
`optimization_type`	string	required	Type of optimization (e.g., “token_guardrails”, “model_switch”)
`payload`	object	—	Override the default optimization payload

`metrx_route_model`

Get a model routing recommendation for a specific task based on complexity. Routes simple tasks to cheaper models while keeping complex tasks on premium models.

Parameter	Type	Default	Description
`agent_id`	UUID	required	The agent to route for
`task_complexity`	`low` \| `medium` \| `high`	required	Estimated task complexity
`current_model`	string	—	Currently configured model (e.g., “gpt-4o”)

`metrx_compare_models`

Compare LLM model pricing and capabilities across providers. Works without usage data (Day 0 value).

Parameter	Type	Default	Description
`current_model`	string	—	Model to compare against (e.g., “gpt-4o”)
`tier`	`frontier` \| `balanced` \| `efficient` \| `budget`	—	Capability tier filter
`provider`	string	—	Provider filter (e.g., “openai”, “anthropic”, “google”)

Budgets (3 tools)

`metrx_get_budget_status`

Get the current status of all budget configurations. Shows spending vs limits, warning/exceeded counts, and enforcement modes.

No parameters.

`metrx_set_budget`

Create or update a budget configuration for an agent or the entire organization.

Parameter	Type	Default	Description
`agent_id`	UUID	—	Agent to set budget for (omit for org-wide)
`period`	`daily` \| `monthly`	required	Budget period
`limit_dollars`	number	required	Spending limit in dollars
`warning_pct`	integer (1–99)	80	Percentage that triggers a warning
`enforcement_mode`	`alert_only` \| `soft_block` \| `hard_block`	`alert_only`	How to enforce the limit

`metrx_update_budget_mode`

Change the enforcement mode of an existing budget or pause/resume it.

Parameter	Type	Default	Description
`budget_id`	UUID	required	Budget configuration ID
`enforcement_mode`	`alert_only` \| `soft_block` \| `hard_block`	—	New enforcement mode
`paused`	boolean	—	Pause or resume the budget

Alerts (3 tools)

`metrx_get_alerts`

Get active alerts and notifications — cost spikes, error rate increases, budget warnings, and system health notifications.

Parameter	Type	Default	Description
`severity`	`info` \| `warning` \| `critical`	—	Filter by severity
`unread_only`	boolean	true	Only return unread alerts
`limit`	integer (1–100)	25	Maximum alerts to return

`metrx_acknowledge_alert`

Mark one or more alerts as read/acknowledged.

Parameter	Type	Default	Description
`alert_ids`	UUID[] (1–50)	required	Alert IDs to acknowledge

`metrx_get_failure_predictions`

Get predictive failure analysis — upcoming risk of error rate breaches, latency degradation, cost overruns, and budget exhaustion.

Parameter	Type	Default	Description
`agent_id`	UUID	—	Filter for a specific agent
`severity`	`info` \| `warning` \| `critical`	—	Filter by severity
`status`	`active` \| `acknowledged` \| `resolved`	`active`	Filter by status

Experiments (3 tools)

`metrx_create_model_experiment`

Start an A/B test comparing two LLM models. Routes a percentage of traffic to the treatment model and tracks cost, latency, error rate, and quality metrics.

Parameter	Type	Default	Description
`agent_id`	UUID	required	Agent to run the experiment on
`name`	string (1–100)	required	Human-readable experiment name
`treatment_model`	string	required	Candidate model (e.g., “gpt-4o-mini”)
`traffic_pct`	integer (1–50)	10	Percentage of traffic to the treatment
`primary_metric`	`cost_per_call` \| `latency_p50` \| `latency_p95` \| `error_rate` \| `quality_score`	`cost_per_call`	Metric to optimize for
`max_duration_days`	integer (1–30)	14	Maximum experiment duration
`auto_promote`	boolean	false	Auto-apply the winner when experiment concludes

`metrx_get_experiment_results`

Get results of a model experiment — sample counts, metric comparisons, statistical significance, and the current winner.

Parameter	Type	Default	Description
`agent_id`	UUID	—	Filter by agent
`status`	`running` \| `paused` \| `completed` \| `cancelled`	—	Filter by status

`metrx_stop_experiment`

Stop a running experiment. Results are preserved.

Parameter	Type	Default	Description
`experiment_id`	UUID	required	Experiment ID to stop
`promote_winner`	boolean	false	Apply the winning model as the new default

Cost Leak Detector (1 tool)

`metrx_run_cost_leak_scan`

Run a comprehensive cost leak audit. Identifies 7 types of cost inefficiencies: idle agents, model overprovisioning, missing caching, high error rates, context bloat, missing budgets, and cross-provider arbitrage opportunities.

Parameter	Type	Default	Description
`agent_id`	UUID	—	Scan a specific agent (omit for fleet-wide)
`include_low_severity`	boolean	false	Include low-severity findings
`output_format`	`text` \| `json`	`text`	Output format (`json` for CI/CD pipelines)

Attribution (3 tools)

`metrx_attribute_task`

Link an agent task/event to a business outcome for ROI tracking.

Parameter	Type	Default	Description
`agent_id`	UUID	required	Agent to attribute
`event_id`	string	—	Specific event/task ID
`outcome_type`	`revenue` \| `cost_saving` \| `efficiency` \| `quality`	required	Type of outcome
`outcome_source`	`stripe` \| `calendly` \| `hubspot` \| `zendesk` \| `webhook` \| `manual`	required	Source of the outcome data
`value_cents`	integer	—	Outcome value in cents
`description`	string	—	Description of the outcome

`metrx_get_task_roi`

Calculate return on investment for an agent — total costs, total outcomes, ROI multiplier, and breakdown by model and outcome type.

Parameter	Type	Default	Description
`agent_id`	UUID	required	Agent to calculate ROI for
`days`	integer (1–365)	30	Number of days to analyze

`metrx_get_attribution_report`

Get an attribution report showing which agent actions led to business outcomes.

Parameter	Type	Default	Description
`agent_id`	UUID	—	Filter to specific agent
`days`	integer (1–365)	30	Number of days to include
`model`	`direct` \| `last_touch` \| `first_touch`	`direct`	Attribution model

Alert Configuration (1 tool)

`metrx_configure_alert_threshold`

Set up cost or operational alert thresholds. Alerts run server-side and can trigger email notifications, webhooks, or automatically pause the agent.

Parameter	Type	Default	Description
`agent_id`	UUID	—	Specific agent (omit for org-wide)
`metric`	`daily_cost` \| `monthly_cost` \| `error_rate` \| `latency_p99`	required	Metric to monitor
`threshold_value`	number	required	Threshold (costs: cents, rates: decimal, latency: ms)
`action`	`email` \| `webhook` \| `pause_agent`	required	Action when threshold is breached

ROI Audit (1 tool)

`metrx_generate_roi_audit`

Generate a comprehensive ROI audit report for your fleet. Includes per-agent cost/revenue breakdown, attribution confidence scores, optimization opportunities, and risk flags. Suitable for board reporting and compliance.

Parameter	Type	Default	Description
`days`	integer (7–365)	30	Analysis period
`include_methodology`	boolean	true	Include methodology notes for auditors
`agent_ids`	UUID[]	—	Specific agents (omit for full fleet)

Upgrade Justification (1 tool)

`metrx_get_upgrade_justification`

Generate an ROI report for upgrading from Free to a paid tier. Analyzes usage patterns and calculates optimization potential.

Parameter	Type	Default	Description
`days`	integer (7–90)	30	Days to analyze

Upgrade Business Case (1 tool)

`metrx_get_upgrade_business_case`

Generate a personalized ROI business case for upgrading to a higher tier with projected savings and payback period.

Parameter	Type	Default	Description
`current_tier`	`starter` \| `lite` \| `pro`	required	Current subscription tier
`monthly_spend`	number	—	Known monthly LLM spend in cents
`agent_count`	integer	—	Number of active agents
`primary_use_case`	`customer_support` \| `data_processing` \| `content_generation` \| `code_assistant`	—	Primary use case

Guided Prompts

MCP prompts are interactive templates that walk agents through multi-step workflows. Use them from any MCP-compatible client.

`analyze-costs`

Step-by-step cost analysis: fetches cost summary → lists agents → gets optimization recommendations → returns a prioritized breakdown.

Argument	Type	Description
`days`	string (optional)	Number of days to analyze (default: “30”)

`find-savings`

Discovers optimization opportunities: checks recommendations → runs cost leak scan → explains savings in dollars.

No arguments.

`cost-leak-scan`

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

Argument	Type	Description
`agent_id`	string (optional)	Scan a specific agent by UUID, or omit to scan all

Rate Limiting

The MCP server enforces 60 requests per minute per tool to prevent abuse. Hitting the limit returns an error with a retryAfter value.

Error Handling

All tools return standardized error responses:

{
  "content": [{ "type": "text", "text": "Error message" }],
  "isError": true
}

Status	Meaning	Fix
401	Invalid or expired API key	Regenerate key
403	Insufficient permissions	Check key permissions
404	Resource not found	Use `metrx_list_agents` to get valid IDs
429	Rate limited	Wait for `retryAfter` seconds
5xx	Server error	Retry with backoff

Troubleshooting

“METRX_API_KEY not set” — Set the environment variable before starting:

export METRX_API_KEY=sk_live_your_key
npx @metrxbot/mcp-server

“Rate limit exceeded” — You’ve made more than 60 requests to a single tool within 60 seconds. The MCP client will retry automatically.

“Agent not found” — The agent_id doesn’t exist. Run metrx_list_agents to get valid IDs.

Connection test fails — Run npx @metrxbot/mcp-server --test to verify your API key and network connectivity.

Quick Start API Reference