Connect an AI app with MCP

MCP (Model Context Protocol) is how an AI app talks to BeanHub. Hosted BeanHub MCP lives at https://api.beanhub.io/mcp. The app signs in with OAuth. It does not use a CLI access token.

This page is the hosted server. A local bh mcp server that reads files on your laptop is a different tool.

Caution

AI models can generate incorrect results. Check numbers, accounts, and any proposed book changes before you rely on them. BeanHub only relays the MCP request and response between your books and the app you connect. BeanHub cannot verify that the model’s output is accurate.

Each model provider has its own privacy policy. Read it and decide whether it is acceptable before you connect. BeanHub does not control how the app or the model uses data it receives. If privacy is a concern, use a local LLM that stays on your computer.

What an app can do

With read access the app can list books, accounts, entries, files, forms, and commits, and it can search transactions and balances. With updates it can add or change entries, rename accounts, submit a custom form, or rewrite ledger files. Every update is the same path as the website: a Git commit after Beancount validation.

The app cannot mint access tokens, change billing, connect a bank, dump Connect or Inbox data, make a book public, or delete a book.

Enable MCP

MCP is off until you turn it on.

1. Sign in at https://app.beanhub.io.
2. Open Account Settings, then Manage MCP, or go to https://app.beanhub.io/mcp/.
3. Turn on Enable Model Context Protocol (MCP).
4. Click Save MCP settings.

Copy the server URL from that page: https://api.beanhub.io/mcp. That is what you paste into the AI app. Do not paste https://app.beanhub.io/mcp/. That is this settings page, not the MCP server.

New connections start read-only and unpaused. You choose books on the connect screen. You can allow updates later without reconnecting.

Connect an app

Enable MCP first. In the AI app, add a custom MCP server and paste https://api.beanhub.io/mcp. The app opens BeanHub’s connect page. Sign in if asked, pick books, leave Allow this app to update books off unless you want writes, then click Allow access.

The token BeanHub issues has only the scopes you granted, even if the app asked for more. You do not start this flow from MCP settings. The AI app starts it.

ChatGPT

Hosted BeanHub MCP works with ChatGPT on the web through developer mode. OpenAI lists Plus, Pro, Business, Enterprise, and Education. These steps follow that developer-mode article, not a logged-in ChatGPT session in this guide. Labels move as ChatGPT ships UI changes.

1. Enable MCP in BeanHub and copy https://api.beanhub.io/mcp.
2. In ChatGPT, turn on Developer mode. OpenAI’s current developer docs put this under Settings → Security and login. Workspace help also mentions Settings → Apps → Advanced settings. If you do not see the toggle, your plan or workspace admin settings do not include custom MCP yet.
3. Go to ChatGPT Plugins (or Settings → Apps → Create on a Business or Enterprise workspace). After developer mode is on, use the plus button to create a custom app.
4. Paste https://api.beanhub.io/mcp as the MCP server URL. Choose OAuth. Do not paste an access token, and do not add a static client secret. BeanHub registers the app itself.
5. Complete BeanHub’s connect page. Leave Allow this app to update books off unless you want ChatGPT to change the book.
6. In a conversation, open the plus menu, choose Developer mode, and enable the BeanHub app.

OpenAI’s help article: Developer mode and MCP apps in ChatGPT.

Claude

Claude custom connectors use remote MCP. Anthropic documents this in Get started with custom connectors using remote MCP. Free plans are limited to one custom connector. These steps follow that article. The add-connector form itself needs a Claude account.

1. Enable MCP in BeanHub and copy https://api.beanhub.io/mcp.
2. In Claude, open Customize → Connectors.
3. Click +, then Add custom connector.
4. Paste https://api.beanhub.io/mcp as the server URL.
5. Skip Advanced settings OAuth client ID and client secret. BeanHub uses dynamic client registration with token_endpoint_auth_method=none. You do not mint those values.
6. Click Add. Complete BeanHub’s connect page.
7. In a conversation, click + → Connectors and enable BeanHub.

Team and Enterprise owners add the connector under Organization settings → Connectors first. Members then click Connect on that row.

Grok

Grok custom MCP connectors are documented by xAI in Connectors. These steps follow that page. The New Connector form itself needs a Grok account.

1. Enable MCP in BeanHub and copy https://api.beanhub.io/mcp.
2. Open https://grok.com/connectors.
3. Click New Connector, then Custom.
4. Paste https://api.beanhub.io/mcp as the MCP server URL.
5. Complete BeanHub’s connect page when Grok starts OAuth.

Grok Business and Enterprise need a team admin to provision the connector before members can use it.

Cursor

Cursor connects to a remote MCP server over HTTP and signs in with OAuth. Do not put a BeanHub access token in headers. Cursor will open BeanHub’s connect page.

Settings UI

1. Enable MCP in BeanHub and copy https://api.beanhub.io/mcp.
2. Open Cursor Settings → Tools & MCP, or Customize → MCPs.
3. Add a custom MCP server. Set the URL to https://api.beanhub.io/mcp.
4. Complete BeanHub’s connect page.

Cursor’s labels move between builds. If you do not see Tools & MCP, use Customize in the sidebar, then MCPs. Cursor also documents this in How do I install an MCP server manually?.

mcp.json

Project file: .cursor/mcp.json. Global file: ~/.cursor/mcp.json.

{
  "mcpServers": {
    "beanhub": {
      "url": "https://api.beanhub.io/mcp"
    }
  }
}

Do not add a headers bearer token. Do not add Cursor’s static auth client ID unless BeanHub has given you one. Hosted BeanHub supports dynamic client registration, so the url field is enough.

Other apps

Any remote MCP client that speaks OAuth can use https://api.beanhub.io/mcp. The app must be able to register a public OAuth client (no client secret) and open a browser for BeanHub’s connect page.

Google Gemini Enterprise custom MCP is a Google Cloud admin setup, not the consumer Gemini app. It is not covered here.

Pause, updates, and revoke

Connected apps are listed under Connected apps on MCP settings. Each row has an Allow updates switch and a Paused switch, plus Edit books and Revoke.

You can pause, drop to read-only, or revoke later without talking to the app.

Pause and resume

Turn the Paused switch on to shut the gate and keep the connection. The grant, refresh token, and client stay. The next MCP call returns an error that the connection is paused. Refresh still works so the app does not think it was kicked. Turn Paused off to resume. Existing unexpired access tokens work again.

Use Paused when you want a break. Use Revoke when you want the app gone.

Read-only and updates

Access	Meaning
Read-only	The app can read ledger data and files for the books you selected. mcp.read
Can update	The app can also mutate those books. mcp.write plus mcp.read

The Allow updates switch on the connected-app row changes the grant immediately. Turn it on to grant write. Turn it off to drop the app to read-only. The next tools/list hides or shows write tools. Write calls on a read-only grant return a tool error. Tokens are not revoked.

Edit books opens the same book picker as connect. You can also allow updates there. No re-OAuth.

Revoke

Revoke forgets the app. The grant and tokens die. The app must connect again. Confirm before you revoke.

Disable MCP on the account

Turn off Enable Model Context Protocol (MCP) and save. That closes the account gate. Connected apps stay. Individually paused apps stay paused. Enable MCP again and unpaused connections work with their existing tokens.

Disable is not Revoke. Revoke one row if you want that app gone.

Note

OAuth metadata: https://api.beanhub.io/.well-known/oauth-authorization-server and https://api.beanhub.io/.well-known/oauth-protected-resource/mcp. The HTTP API uses Authorization: Bearer with a CLI access token. The access-token header still works and is deprecated. See API overview.