MCP Costs & Budget API
Track per-server spending, set monthly budgets, and automatically block requests when the budget is exceeded. Each tool call records a cost, and the proxy aggregates totals monthly with a per-tool breakdown.
Base URL
https://api.hookwatch.dev/v1/mcp/servers/:id/costsHow It Works
- Every tool call proxied through an MCP server records a cost (default:
default_cost_centsfrom the server configuration, typically 1 cent). - Costs are aggregated monthly per server.
- Before each tool call, the proxy checks the current month's spend against the configured budget.
- When the budget is exceeded, the proxy returns
429 Too Many Requestswith a JSON-RPC error. - When spending crosses the alert threshold, a notification is sent via your configured alert channels.
The Monthly Cost Summary Object
Properties
| Field | Type | Description |
|---|---|---|
total_cents | int | Total cost in cents for the requested month |
budget_cents | int | Configured monthly budget in cents. 0 if no budget is set. |
usage_percent | float | Percentage of budget used. 0 if no budget is configured. |
tool_breakdown | array | Per-tool cost breakdown, sorted by total cost descending |
tool_breakdown[].tool_name | string | Name of the tool |
tool_breakdown[].total_cents | int | Total cost in cents for this tool during the month |
tool_breakdown[].call_count | int | Number of times this tool was called during the month |
Get Cost Summary
Retrieve the monthly cost summary for a specific MCP server. If no query parameters are provided, the current month is returned.
GET /v1/mcp/servers/:id/costsBoth query parameters are optional and default to the current date.
Path Parameters
| Field | Type | Description |
|---|---|---|
id | string | The MCP server UUID |
Query Parameters
| Field | Type | Description |
|---|---|---|
year | int | Year to query (defaults to current year) |
month | int | Month to query, 1–12 (defaults to current month) |
Example
Response
Budget Configuration
Budget settings are configured via the rate_limit_config.cost field on the MCP server object. Update it using the Servers API.
Cost Configuration Object
Properties
| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | Yes | Whether cost tracking and budget enforcement are enabled |
monthly_budget_cents | int | Yes | Maximum monthly spend in cents. When exceeded, the proxy returns 429 Too Many Requests. |
alert_threshold_percent | float | No | Percentage of budget at which an alert notification is triggered (e.g., 80 for 80%) |
Example — Set a Monthly Budget
Default behaviour
Cost tracking is disabled by default. You must explicitly set enabled to true and provide a monthly_budget_cents value to activate
budget enforcement.
Budget Exceeded Behaviour
When a tool call would push the monthly spend over the configured budget, the proxy rejects
the request with a 429 Too Many Requests HTTP status and a JSON-RPC error body:
Budget is checked before execution
The budget check occurs before the tool call is forwarded to the upstream server. If the budget has already been exceeded, the call is never made.
Error Codes
| Status | Error | Description |
|---|---|---|
401 | Unauthorized | Invalid or missing access token |
404 | Not Found | MCP server not found |
429 | Too Many Requests | Monthly budget exceeded — tool call blocked |
500 | Internal Error | Unexpected server error while retrieving cost data |