Budget & Limits

Configure safety limits to prevent runaway provider costs.

BYOK Pricing: Budget tracking monitors your provider costs (OpenAI, Anthropic, Google, xAI bills), not RelayPlane fees. RelayPlane is BYOK (Bring Your Own Keys), we do not charge for API usage.

Default Limits

LimitDefaultPurpose
Daily budget$5.00Maximum provider spend per day (resets at midnight UTC)
Single call limit$0.50Maximum cost for any single API call
Calls per hour100Rate limit to prevent runaway loops

How It Works

Before each API call, the MCP server:

  • 1.Estimates the cost based on prompt length and model pricing
  • 2.Checks against single-call limit, rejects if too expensive
  • 3.Checks against daily budget, rejects if would exceed
  • 4.Checks hourly rate limit, rejects if too many calls
  • 5.After execution, records actual cost for accurate tracking

Error Messages

When a limit is exceeded, you'll see clear error messages:

Daily Budget Exceeded

1{
2  "error": {
3    "code": "BUDGET_EXCEEDED",
4    "message": "Daily provider budget exceeded. Estimated spend: $4.82 / $5.00. This tracks your OpenAI/Anthropic bills, not RelayPlane fees (we're BYOK). Resets at midnight UTC. Use relay_workflow_validate (free) for syntax checks."
5  }
6}

Single Call Limit Exceeded

1{
2  "error": {
3    "code": "SINGLE_CALL_LIMIT",
4    "message": "Estimated provider cost ($0.72) exceeds single-call limit ($0.50). Try a smaller model (gpt-5-nano) or shorter prompt."
5  }
6}

Rate Limit Exceeded

1{
2  "error": {
3    "code": "RATE_LIMIT",
4    "message": "Hourly call limit reached (100 calls). Use relay_workflow_validate (free) for syntax checks, or wait for reset."
5  }
6}

Configuring Limits

CLI Flags

1# Increase daily budget to $10
2claude mcp add relayplane -- npx @relayplane/mcp-server --max-daily-cost 10
3
4# Increase single-call limit to $1
5claude mcp add relayplane -- npx @relayplane/mcp-server --max-single-call-cost 1
6
7# Increase rate limit to 200/hour
8claude mcp add relayplane -- npx @relayplane/mcp-server --max-calls-per-hour 200
9
10# All options
11claude mcp add relayplane -- npx @relayplane/mcp-server \
12  --max-daily-cost 10 \
13  --max-single-call-cost 1 \
14  --max-calls-per-hour 200

Config File

Create ~/.relayplane/mcp-config.json:

1{
2  "maxDailyCostUsd": 10.00,
3  "maxSingleCallCostUsd": 1.00,
4  "maxCallsPerHour": 200
5}

Free Tools

These tools never count against your budget:

  • Freerelay_workflow_validate, Validate workflow structure without LLM calls
  • Freerelay_models_list, List available models
  • Freerelay_skills_list, Discover pre-built skills
  • Freerelay_runs_list, View recent runs
  • Freerelay_run_get, Get run details
Use relay_workflow_validate to check workflow syntax before running. This catches structural errors without spending on provider costs.

Cost Estimation

The server estimates costs using current model pricing (per 1M tokens):

ModelInput ($/1M)Output ($/1M)
openai:gpt-5.2$5.00$20.00
openai:gpt-5-mini$1.00$4.00
openai:gpt-5-nano$0.25$1.00
anthropic:claude-sonnet-4-5-20250929$3.00$15.00
anthropic:claude-haiku-4-5-20251001$0.80$4.00
google:gemini-3-flash$0.075$0.30
xai:grok-4-fast-reasoning$0.20$0.50

Cost-Saving Tips

  • 1.Use cheaper models for simple tasks: gpt-5-nano and claude-haiku-4-5-20251001 are 10-20x cheaper than flagship models
  • 2.Validate before running: Use relay_workflow_validate to catch errors without spending
  • 3.Use skills: Pre-built skills are optimized for cost and quality
  • 4.Batch workflows: Multi-step workflows are more efficient than individual calls

Next Steps