Integration

OAuth & MCP documentation

PocketLedger exposes scoped OAuth endpoints and a remote MCP endpoint so ChatGPT can record, search, update, undo, and summarize expenses after user approval.

Public endpoints

MCP endpoint

/mcp

Authorization metadata

/.well-known/oauth-authorization-server

Protected resource metadata

/.well-known/oauth-protected-resource

MCP resource metadata

/.well-known/oauth-protected-resource/mcp

Authorization endpoint

/oauth/authorize

Token endpoint

/oauth/token

Token revocation

/oauth/revoke

Dynamic client registration

/oauth/register

Google Sign-In endpoints

Google Sign-In is separate from the MCP OAuth server. It is used only to authenticate a PocketLedger user account before OAuth consent.

Start Google login

/auth/google/

Google callback

/auth/google/callback/

Scopes

account:read — read account and category information.
account:write — update account defaults such as currency, timezone, and locale.
transactions:read — search and inspect saved transactions.
transactions:write — create, update, delete, restore, and undo transactions.
reports:read — read spending summaries and chart-ready grouped reports.

Available MCP tools

record_expense, parse_expense_text, log_transaction, update_transaction, delete_transaction, restore_transaction, undo_last_transaction, search_transactions, get_summary, get_report, list_categories, get_connected_account, and update_account_settings.

Connector setup

Add https://pocketledger.baronsa.dev/mcp as the remote MCP endpoint.
Complete OAuth authorization with PKCE.
Approve the requested scopes.
Test list_categories.
Record a small test expense, search it, undo or restore it, then request a spending report.

ChatGPT app behavior

After the user approves OAuth consent, ChatGPT can call only the PocketLedger tools allowed by the approved scopes. Read-only scopes allow account, transaction, category, and report access. Write scopes allow transaction changes such as create, update, delete, restore, and undo, plus account preference updates when account:write is approved.

Security notes

PocketLedger uses authorization code flow with PKCE, scoped OAuth grants, refresh-token rotation, token revocation, idempotency protection for write tools, and audit-friendly transaction workflows.

Browser-origin MCP requests are checked against an allowlist for supported assistant origins such as ChatGPT, Claude, Grok, Gemini, Cursor, Microsoft Copilot, VS Code, and Perplexity. Server-to-server clients that do not send an Origin header can continue to work.

Reviewer account

Directory reviewers should receive test credentials through the submission form. The reviewer account should include sample transactions across multiple categories and currencies so read, write, search, undo, restore, and report tools can be tested end to end.

Troubleshooting

Authorization fails

Make sure the user is signed in to the correct PocketLedger account, the redirect URI is valid, and the OAuth client requested supported scopes.

Google Sign-In fails

Confirm that Google OAuth credentials exist in the backend environment and that /auth/google/callback/ is registered as an allowed redirect URI in Google Cloud.

Write tools create duplicate records

Write tools should use idempotency protection where available. If a duplicate is created, use delete, restore, or undo tools to correct the transaction history.

Manage active connections in Settings → AI connections or Profile → Settings.

API host: https://pocketledger.baronsa.dev · Site: https://pocketledger.baronsa.dev