SuperBooks MCP
Work with your SuperBooks books: transactions and categories, invoices, customers, receipts, time tracking and financial reports. Remote server with OAuth sign-in.
Hosted MCP Server
npx add-mcp 'https://app.superbooks.io/mcp'Installs into Claude Code, Codex, Cursor and more
Documentation
Point Claude, Claude Code, Cursor, or any MCP client at SuperBooks over the remote URL.
SuperBooks is an MCP server, so any MCP-capable client can use it without a plugin or an adapter. The endpoint is:
https://app.superbooks.io/mcp
It speaks Streamable HTTP, and clients connect to that URL directly.
What a client sees
Connect any MCP client and its tools/list shows exactly two tools: search_tools and execute_typescript. This is Code Mode: instead of one MCP tool per SuperBooks operation, the assistant calls search_tools to discover the operations your credential can reach, then writes and runs a short TypeScript program with execute_typescript that calls them. Every feature of the app is a real SuperBooks tool (244 of them: books, invoicing, reports, time tracking, bank and app connections, billing, account, team, support and API keys), reached this way rather than listed directly — see The tool surface. Each one still carries its own scope and authentication exactly as if the client had called it directly. The 120-per-minute rate limit counts MCP requests, not tool calls: one request counts once, whether it runs a single tool or an execute_typescript program that calls several.
Choosing between a key and OAuth
Clients that support remote MCP servers with OAuth — Claude among them — can sign you in through the SuperBooks consent screen. Nothing to copy, nothing to store, and access is revocable from the app.
Clients that expect a static header want an API key instead. Create one with the create_api_key tool from any connected agent, or on the Developer settings page; see Authentication.
Claude
Claude connects over OAuth, so you do not handle a key at all.
Fastest: Add SuperBooks to Claude opens SuperBooks' listing in Claude's connector directory. Select Connect, then sign in; the connector syncs to Claude Desktop and mobile.
Or by hand, as a custom connector:
- Open Settings → Connectors.
- Choose Add custom connector.
- Enter
https://app.superbooks.io/mcp. - Claude registers itself, then sends you to SuperBooks to sign in, choose which of your teams it can use, and approve the scopes it asked for.
search_tools and execute_typescript are then available in the conversation, and Claude uses them to find and call the real SuperBooks tools — see What a client sees. Revoke access any time from the same Connectors screen or from the SuperBooks app.
Verified clients on the consent screen
The consent screen marks well-known AI clients such as Claude and Perplexity as Verified, with their own name and logo. SuperBooks decides that from the addresses the client registered to receive your approval: every one must be that company's own published sign-in address, on its own website. The name and logo a client sends about itself play no part, because any program can claim any name.
A well-known client running on your own computer, such as Claude Code, says Runs on your computer instead: SuperBooks recognises its name and its local sign-in address, but cannot prove who is listening there.
Every other client shows as Not verified by SuperBooks, with the full address it will send you back to and a box, I recognize this address, that you tick before Allow access works. That is not an error. It asks you to check that you set the connection up yourself.
One connection, several teams
A SuperBooks account can belong to several teams, and one connection can cover more than one of them. On the consent screen you choose either:
- All my teams: every team you are a member of when a request arrives, including teams you join later.
- Specific teams: only the teams you tick. Tick at least one.
Pick the narrowest grant that does the job: tick specific teams rather than all of them, because an assistant working in several teams can carry what it reads in one into another.
One connection covers at most 100 teams. An All my teams connection for someone in more than 100 teams is refused, and the message says to connect again and tick specific teams.
SuperBooks checks your membership on every request, not only when you connect. Leave a team and the connection stops reaching it straight away. If you are no longer a member of any team it covers, requests are refused until you connect again and choose.
When a connection covers one team, every tool works on that team and nothing else changes. When it covers several, each tool that reads or changes a team's data takes an optional teamId argument:
list_teamsreturns the teams the connection covers, with each team's id, name and your role in it. It needs only read access.- Pass
teamIdto pick the team for that call. - A call without
teamIdis refused withTEAM_REQUIRED, and the message lists the teams to choose from by name and id. - A
teamIdthe connection does not cover is refused withTEAM_NOT_AVAILABLE. The message is the same whether or not a team with that id exists.
Permissions are worked out per team. A read-only connection is read-only in every team. Tools that delete, send or overwrite data ask your agent to confirm once with a single-use token before they run.
An API key belongs to one team. Its tools always work on that team, and a teamId naming any other team is refused.
Claude Code
One command, using an API key:
claude mcp add --transport http superbooks https://app.superbooks.io/mcp \
--header "Authorization: Bearer sb_your_api_key_here"
Then check it is live:
claude mcp list
Cursor
Add SuperBooks to ~/.cursor/mcp.json (global) or .cursor/mcp.json in a project:
{
"mcpServers": {
"superbooks": {
"url": "https://app.superbooks.io/mcp",
"headers": {
"Authorization": "Bearer sb_your_api_key_here"
}
}
}
}
Restart Cursor, and search_tools / execute_typescript appear under Settings → MCP — see What a client sees.
Windsurf
Windsurf uses the same shape, in ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"superbooks": {
"serverUrl": "https://app.superbooks.io/mcp",
"headers": {
"Authorization": "Bearer sb_your_api_key_here"
}
}
}
}
Connect from any MCP client
Buttons for Claude and ChatGPT open SuperBooks' directory listings; the others install directly or jump to the instructions.
The SuperBooks MCP server is a hosted Streamable HTTP endpoint with OAuth 2.1 sign-in. There is nothing to install or run: point the client at the URL below and sign in to SuperBooks when the browser opens. Every client that supports remote MCP servers with OAuth works; the ones below are the common ones. The Claude Code, Cursor and Windsurf sections above show the API-key form of the same setup, for a client that should not sign in interactively.
https://app.superbooks.io/mcp
Claude (claude.ai, Claude Desktop, Claude Code)
- claude.ai / Claude Desktop: open SuperBooks in the Claude connector directory and click Connect, or follow the custom-connector steps under Claude above.
- Claude Code:
claude mcp add --transport http superbooks https://app.superbooks.io/mcpthen/mcpto sign in.
ChatGPT and Codex
- ChatGPT: open SuperBooks in ChatGPT, select Connect, then sign in. Manual: Settings → Apps & Connectors → Create (developer mode), name it SuperBooks, paste the URL, authentication OAuth.
- Codex CLI: add to
~/.codex/config.toml:
[mcp_servers.superbooks]
url = "https://app.superbooks.io/mcp"
Cursor
One click: Add to Cursor. Or the .cursor/mcp.json entry from the Cursor section above without its headers block, which makes Cursor sign in over OAuth instead:
{ "mcpServers": { "superbooks": { "url": "https://app.superbooks.io/mcp" } } }
VS Code and GitHub Copilot
One click: Add to VS Code. Or run MCP: Add Server → HTTP and paste the URL, which writes to .vscode/mcp.json:
{ "servers": { "superbooks": { "type": "http", "url": "https://app.superbooks.io/mcp" } } }
Google Antigravity
Install the plugin from the repository (or from the Antigravity Marketplace once listed):
agy plugin install https://github.com/DevinoSolutions/mcp-servers/antigravity-plugins/superbooks
Or add the server by hand in ~/.gemini/config/mcp_config.json (Antigravity requires the serverUrl key):
{ "mcpServers": { "superbooks": { "serverUrl": "https://app.superbooks.io/mcp" } } }
Gemini
- Gemini app: Settings → Connected apps → Custom apps → Add a custom app, paste the URL, then mention
@SuperBooksin a chat. (Custom apps are currently limited to personal Google accounts in the US.) - Gemini CLI:
gemini extensions install https://github.com/DevinoSolutions/mcp-serversthen/mcp auth superbooks, or add{ "mcpServers": { "superbooks": { "httpUrl": "https://app.superbooks.io/mcp" } } }to~/.gemini/settings.json.
Kiro
One click: Add to Kiro. Or in .kiro/settings/mcp.json:
{ "mcpServers": { "superbooks": { "url": "https://app.superbooks.io/mcp" } } }
Perplexity, Mistral Le Chat, Grok
- Perplexity (Pro, Max, Enterprise): Settings → Connectors → Custom connector, paste the URL, authentication OAuth.
- Mistral Le Chat (all plans): Intelligence → Connectors → Add Connector → Custom MCP Connector, paste the URL.
- Grok: grok.com → Connectors → New connector → Custom, paste the URL.
Other clients
- Replit: Add to Replit, or Integrations → Add MCP server.
- Devin, Windsurf, Zed, JetBrains Junie, Cline, OpenCode: add a remote (HTTP) MCP server with the URL above; each prompts for the OAuth sign-in on first use. Cline can also install it from the Cline marketplace entry using its
llms-install.md.
Tokens are scoped to what you approve on the consent screen; a tool you did not grant is never shown to the assistant. Revoke access at any time with the connected_apps_revoke tool, or from the Connected apps settings page.
The tool surface
Every feature of the app is reachable through search_tools and execute_typescript (see What a client sees) — not what a raw tools/list call returns, which is always just those two. The core is listed below: 53 tools across 12 domains, plus list_teams for choosing a team when a connection covers several. The rest of the 244 cover billing, account, team, API keys, bank and app connections, support and every other screen of the app; the full list, with each tool's tier, is mcp-tool-catalog.json, and search_tools with a query finds any of them. What a given credential's search_tools call actually declares depends on its scopes — see How scopes gate the tool surface.
| Domain | Tools | Destructive | What it covers |
|---|---|---|---|
transactions | 9 | 1 | Bank transactions, categorisation, attached receipts |
invoices | 5 | 1 | Drafting, sending, and voiding invoices |
customers | 5 | 1 | The customer book |
tracker | 5 | 1 | Time-tracking projects and entries |
categories | 4 | 1 | Transaction categories |
documents | 6 | 1 | Uploaded files, their contents, and uploading |
tags | 3 | 1 | Labels across customers, transactions, projects |
inbox | 3 | 1 | Incoming receipts and bills, and matching them |
reports | 8 | 0 | Revenue, profit and loss, burn rate, runway, spending |
bank_accounts | 1 | 0 | Connected accounts |
search | 1 | 0 | Cross-domain search |
team | 1 | 0 | The current team's profile |
list_teams | 1 | 0 | The teams a connection covers; MCP only, not the SDKs |
The eight destructive tools are the seven *_delete tools plus invoices_void (a soft cancel, not a delete), and they are gated twice over — see Destructive tools need full access and a confirmation.
Uploading files
Receipts and vendor invoices go in with two calls, because the file bytes never travel through the tool API.
documents_create_upload_urltakesfilename,mime_type(PDF, PNG, JPEG, WebP or HEIC/HEIF),size(at most 5,000,000 bytes) anddestination:inbox(the default, for receipts and invoices you want matched to transactions) orvault(general document storage). It returns anupload_urland theupload_headersto send.- Send the file to
upload_urlwith an HTTPPUTcarrying exactly those headers. This step runs in your own code, not inside the Code Mode sandbox, which has no network access. documents_finalize_uploadtakes theupload_id. It checks the size and that the content really is the declared type, then starts processing. A file that fails the check is discarded.
Then transactions_attach_document links the stored file to a transaction, by inbox_id or document_id, and transactions_detach_document undoes it without deleting the file. Uploading the same filename twice stores two separate files.
Troubleshooting
The client shows no tools, or fails to connect. Check the credential first: a 401 comes back with a WWW-Authenticate header pointing at the OAuth metadata. If you are using a key, confirm it starts with sb_ and still exists (list_api_keys, or the Developer settings page). (The client's own tool list always shows exactly search_tools and execute_typescript regardless of scopes — a missing credential shows up as a 401, never as a shorter tool list.)
search_tools returns fewer operations than expected. That is scopes working as designed. A read-only key sees the read tier only. Destructive tools additionally need apis.all plus the team setting.
A tool call fails with TEAM_REQUIRED. The connection covers more than one team. Call list_teams, then repeat the call with the teamId of the team you mean.
Requests are refused after you left a team. The connection no longer covers any team you are a member of. Connect again and choose your teams.
A destructive tool returns CONFIRMATION_REQUIRED. That is the first half of a confirmation, not a failure. Repeat the same call with the confirmToken from next.args; the token works once and expires after ten minutes. Under Code Mode, repeat it in a new execute_typescript call after the user agrees: the program that received the token cannot use it.
Requests start failing after heavy use. You may be hitting the limit of 120 requests per minute — see Rate limits.
[
Authentication
API keys for your own team, OAuth with PKCE and dynamic client registration for integrators, and how scopes gate the tool surface.
](https://docs.superbooks.io/authentication)[
Rate limits
The per-credential limit on MCP calls, the registration limit, and how to handle a 429.