Authentication

There are two ways to give an app access to your Maple Budget:

	OAuth Sign-In	API Key
Best for	Claude, ChatGPT, Claude Code and other MCP apps	Scripts, the local MCP server, apps without OAuth
How	Paste https://api.maplebudget.com/mcp and sign in	Create a key in AI Apps and send it as a Bearer token
Access	Read Only, or Read And Make Changes	Full access (reads and changes)
Revoke	Disconnect the app in AI Apps	Revoke the key in AI Apps

OAuth Sign-In

The hosted MCP server at https://api.maplebudget.com/mcp uses OAuth 2.1, so most apps connect with nothing more than the address. Your app handles the steps below for you:

1. It calls the server without a token and gets 401 Unauthorized with a WWW-Authenticate header pointing at the server’s metadata.
2. It reads https://api.maplebudget.com/.well-known/oauth-protected-resource/mcp and https://api.maplebudget.com/.well-known/oauth-authorization-server, registers itself (dynamic client registration, or a client ID metadata document) and opens the sign-in page with PKCE (S256).
3. You sign in to Maple Budget in the browser, see which app is asking, and choose Read And Make Changes or Read Only.
4. Your app gets an access token and a refresh token and sends Authorization: Bearer <access token> on every request.

Details for client developers:

Setting	Value
Authorize	https://api.maplebudget.com/oauth/authorize
Token	https://api.maplebudget.com/oauth/token (grants: authorization_code, refresh_token)
Register	https://api.maplebudget.com/oauth/register
Revoke	https://api.maplebudget.com/oauth/revoke
Scopes	read, write (write includes read). Asking for no scope asks for both.
Client authentication	None (public clients with PKCE)
Access token	Lasts 1 hour
Refresh token	Lasts 30 days and is replaced on every refresh
Sign-in link	Expires after 10 minutes

Because refreshing hands out a new 30-day refresh token, a connection you use keeps working. An app that goes unused for 30 days asks you to sign in again.

Read Only Vs Read And Make Changes

What you choose when you sign in decides which tools the app gets:

• Read Only (read): only the tools that read, the ones named get_… and list_…. The app never sees the others.
• Read And Make Changes (read write): every tool. Tools that change data are marked as destructive, so your app asks you before it uses one.

You can grant less than an app asks for, never more. A connection can’t widen its own access when it refreshes. To switch a Read Only connection to Read And Make Changes, disconnect it in AI Apps and connect again.

The Tool Reference marks every tool as Read Only or Changes Data.

API Keys

API keys are for scripts and for the local MCP server, which runs on your own computer.

1. In the web app, open Menu → AI Apps.
2. Under API Keys, choose Create API Key, give it a name (like “Claude Desktop”) and choose Generate Key.
3. Copy the key. It starts with mbk_ and is shown only once. Maple Budget only keeps a hash of it.

Send it as a Bearer token:

curl -X POST https://api.maplebudget.com/mcp \
  -H "Authorization: Bearer mbk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

For the local server, put the key in the MAPLE_BUDGET_API_KEY environment variable (see Local Server: Quick Setup).

A key isn’t scoped: anything holding it can read and change your data, so keep it private. For an app that should only read, connect it with OAuth and choose Read Only instead.

The hosted server never offers tools that create, list or revoke API keys. The local server does (list_api_keys, create_api_key, revoke_api_key), because it runs on your own computer with your own key.

Revoking Access

Everything connected to your account is in the web app under Menu → AI Apps:

• Connected Apps: each app you signed in to, with Read Only or Read And Make Changes and the date it connected. Choose Disconnect and it stops working right away; it has to sign in again to come back. Connecting the same app again from the same computer replaces its old connection.
• API Keys: choose Revoke next to a key. Anything using it stops working right away, and this can’t be undone.

Apps can also revoke their own tokens at https://api.maplebudget.com/oauth/revoke.

Rate Limits

The hosted MCP server allows 5,000 requests per hour for each connection (one app for one person) or API key. The count resets at the top of each hour. Past the limit, requests get 429 Too Many Requests with a Retry-After header giving the seconds until the reset. See Errors.