Connecting AI clients

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. The 46 real SuperBooks tools (45 across 12 domains, plus list_teams) are 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. Mint one at Settings → Developer; 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.

Every other client, including one running on your own computer, shows as an unverified developer with a warning. That is not an error. It asks you to check that you started the connection yourself before you approve it.

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.
• A destructive tool in a team whose Destructive AI tools setting is off is refused with DESTRUCTIVE_TOOLS_OFF, naming the team. Turn the setting on under Settings > AI in that team; reconnecting does not change it.

Permissions are worked out per team. A read-only connection is read-only in every team, and a destructive tool also needs the setting switched on in the team the call names.

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

[mcp_servers.superbooks]
url = "https://app.superbooks.io/mcp"

{ "mcpServers": { "superbooks": { "url": "https://app.superbooks.io/mcp" } } }

{ "servers": { "superbooks": { "type": "http", "url": "https://app.superbooks.io/mcp" } } }

agy plugin install https://github.com/DevinoSolutions/mcp-servers/antigravity-plugins/superbooks

{ "mcpServers": { "superbooks": { "serverUrl": "https://app.superbooks.io/mcp" } } }

{ "mcpServers": { "superbooks": { "url": "https://app.superbooks.io/mcp" } } }

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 from Settings → Connected apps in SuperBooks.

The tool surface

These are the 46 real SuperBooks tools 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: 45 tools across 12 domains, plus list_teams for choosing a team when a connection covers several. What a given credential's search_tools call actually declares depends on its scopes — see How scopes gate the tool surface.

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 two gates.

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 in Settings → Developer. (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 fails with DESTRUCTIVE_TOOLS_OFF. The team the call named has Destructive AI tools switched off. Switch it on under Settings > AI in that team; connecting again does not change it.

Requests start failing after heavy use. You may be hitting the limit of 120 requests per minute — see Rate limits.