Developer tools

Connect an agent with MCP

Use EnvelopeBudget's remote Model Context Protocol server to review budget data from a compatible AI client. Connections are read-only by default; you can explicitly allow the narrow AI categorization workflow on a dedicated key.

Manage API keys

Connection

Streamable HTTP endpoint
https://envelopebudget.com/mcp
Required header
Authorization: Bearer <API key>

Authentication in v1

OAuth-compatible clients can sign in through your browser, select budgets, and request optional write permissions. Existing developer API keys also work as static Bearer credentials. MCP does not accept the X-API-Key header. Manage MCP connections.

Never paste your API key into a prompt or commit it to source control.

Optional categorization permission

Enable ai-categorization:write when creating a dedicated key if the agent may start categorization jobs and approve or reject selected pending suggestions. A person must accept the current AI disclosure in EnvelopeBudget first. This permission cannot create arbitrary transactions, change amounts or payees, or move funds.

Client configuration

Prefer your client's password prompt, environment interpolation, or secret store. Configuration formats can vary by client version.

Cursor

{
  "mcpServers": {
    "envelopebudget": {
      "url": "https://envelopebudget.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:ENVELOPEBUDGET_API_KEY}"
      }
    }
  }
}

VS Code

{
  "inputs": [{
    "type": "promptString",
    "id": "envelopebudget-key",
    "description": "EnvelopeBudget API key",
    "password": true
  }],
  "servers": {
    "envelopebudget": {
      "type": "http",
      "url": "https://envelopebudget.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:envelopebudget-key}"
      }
    }
  }
}

Claude Desktop

When your version cannot attach a static credential to a remote connector, use mcp-remote:

{
  "mcpServers": {
    "envelopebudget": {
      "command": "npx",
      "args": ["-y", "mcp-remote",
        "https://envelopebudget.com/mcp",
        "--header",
        "Authorization:${ENVELOPEBUDGET_AUTH_HEADER}"
      ],
      "env": {
        "ENVELOPEBUDGET_AUTH_HEADER": "Bearer <API key>"
      }
    }
  }
}

This example stores a plaintext key. Restrict config-file permissions and prefer client-managed secrets when available.

Hermes Agent

mcp_servers:
  envelopebudget:
    url: https://envelopebudget.com/mcp
    headers:
      Authorization: "Bearer <API key>"

Restart Hermes Agent after changing ~/.hermes/config.yaml.

Sample prompts

  • “List my budgets, then summarize this month's available funds, spending, and cashflow for Household.”
  • “Show uncategorized transactions in Household from the last 14 days. Do not include memo text.”
  • “Compare this month's spending by envelope with current envelope balances.”
  • “Review the last 90 days of cashflow and suggest a monthly funding plan. Do not change anything.”
  • “Explain the AI disclosure and summarize existing suggestions. Do not start or approve anything.”
  • “Start AI categorization, show me the suggestions, then approve only the ones I explicitly select.”
  • “Review my uncategorized inbox, then assign only the transactions I confirm to the envelopes we discussed.”

Privacy and safety

  • MCP is read-only by default. Provider suggestions and direct transaction categorization use separate opt-in key scopes.
  • Use a dedicated, expiring key and revoke it immediately if exposed.
  • Treat imported payee and memo text as untrusted; it may contain misleading instructions.
  • Amounts use integer milliunits with currency metadata; 1000 milliunits equals one currency unit.
  • Transaction memo text is omitted by default because it may contain private details.
  • Your budget membership and role still limit which data the agent can read.
  • The agent cannot accept the AI disclosure. Direct assignments require short-lived signed transaction-state tokens and a unique idempotency key.
  • Scoped decisions are owner-only, bounded, attributed to the API key, and undoable. Direct assignment batches are all-or-nothing.
Disconnect a client: rotate or delete its key from API Keys.