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:

  1. Open Settings → Connectors.
  2. Choose Add custom connector.
  3. Enter https://app.superbooks.io/mcp.
  4. 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_teams returns the teams the connection covers, with each team's id, name and your role in it. It needs only read access.
  • Pass teamId to pick the team for that call.
  • A call without teamId is refused with TEAM_REQUIRED, and the message lists the teams to choose from by name and id.
  • A teamId the connection does not cover is refused with TEAM_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/mcp then /mcp to 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 @SuperBooks in a chat. (Custom apps are currently limited to personal Google accounts in the US.)
  • Gemini CLI: gemini extensions install https://github.com/DevinoSolutions/mcp-servers then /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.

DomainToolsDestructiveWhat it covers
transactions91Bank transactions, categorisation, attached receipts
invoices51Drafting, sending, and voiding invoices
customers51The customer book
tracker51Time-tracking projects and entries
categories41Transaction categories
documents61Uploaded files, their contents, and uploading
tags31Labels across customers, transactions, projects
inbox31Incoming receipts and bills, and matching them
reports80Revenue, profit and loss, burn rate, runway, spending
bank_accounts10Connected accounts
search10Cross-domain search
team10The current team's profile
list_teams10The 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.

  1. documents_create_upload_url takes filename, mime_type (PDF, PNG, JPEG, WebP or HEIC/HEIF), size (at most 5,000,000 bytes) and destination: inbox (the default, for receipts and invoices you want matched to transactions) or vault (general document storage). It returns an upload_url and the upload_headers to send.
  2. Send the file to upload_url with an HTTP PUT carrying exactly those headers. This step runs in your own code, not inside the Code Mode sandbox, which has no network access.
  3. documents_finalize_upload takes the upload_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.

](https://docs.superbooks.io/rate-limits)