MCP: connection — Budgeter

MCP (Model Context Protocol) lets you connect AI clients (Cursor, Perplexity, Cloud Code, etc.) to Budgeter. The MCP server runs on the same host as the External API; access is by API key (X-Api-Key header).

Where to get the API key

In the web app: Settings → API. Create a key and copy it — the raw key is shown only once. The same key works for MCP and for POST /v1/... requests.

MCP base URL

Production: https://api-external.budgeter.online/mcp
Local: http://localhost:5102/mcp

Headers

For each request to the MCP endpoint, the client sends X-Api-Key: <your_api_key>. The key is validated the same way as for the External API; the same scopes and rate limits apply.

Config for Cursor

Add the Budgeter server to your MCP settings (e.g. .cursor/mcp.json). Replace YOUR_API_KEY with your key.

Production

{
  "mcpServers": {
    "Budgeter AI": {
      "url": "https://api-external.budgeter.online/mcp",
      "headers": {
        "X-Api-Key": "YOUR_API_KEY"
      }
    }
  }
}

Local development

{
  "mcpServers": {
    "Budgeter AI": {
      "url": "http://localhost:5102/mcp",
      "headers": {
        "X-Api-Key": "YOUR_API_KEY"
      }
    }
  }
}

After saving the config, restart Cursor or refresh the MCP server list. Budgeter Tools (e.g. list accounts, create account) will appear in the tools list.

Errors and limits

Same as the External API: INVALID_API_KEY / API_KEY_REVOKED (401), FORBIDDEN_SCOPE (403), RATE_LIMIT_EXCEEDED (429, Retry-After header), VALIDATION_ERROR (400), RESOURCE_NOT_FOUND (404). Limits: 120 req/min, 3000/hour, 30000/day, 600000/month; 60/min for mutating operations.