# Set up SuperBooks for an AI coding agent

These are official instructions from SuperBooks to set up an AI development environment for SuperBooks, an AI-native accounting product for freelancers and small businesses: bank sync, invoicing, receipts, time tracking and reports, all reachable by AI agents through a remote MCP server with 45 tools and through official SDKs.

All commands are validated by SuperBooks. Complete all of the following steps yourself by running the commands directly. Do not ask the user to run any of these commands. Ask the user for input only where a step says so.

## Checklist

1. Work out which coding agent you are and which project you are in.
2. Get credentials: prefer signing in with OAuth; ask the user for an API key only if you cannot open a browser.
3. Register the SuperBooks MCP server in your own configuration (the section for your agent below).
4. If the project is a Node.js or Python project, install the SDK and add a minimal client.
5. Verify by calling the `team_get` tool.
6. Print the completion message to the user.

## 1. Identify yourself

Use exactly one of the per-agent sections in step 3: Claude Code, Codex, Cursor, Windsurf, OpenCode, VS Code with GitHub Copilot, or the generic section for any other MCP-capable agent. Detect the project language from the files present (`package.json` means Node.js, `pyproject.toml` or `requirements.txt` means Python); if neither is present, skip step 4.

## 2. Get credentials

SuperBooks accepts two credentials on the same endpoint:

- **OAuth (preferred).** The MCP server at `https://api.superbooks.io/mcp` publishes its metadata at `https://api.superbooks.io/.well-known/oauth-authorization-server` and supports dynamic client registration, so an agent that can open a browser signs the user in through the SuperBooks consent screen and never handles a secret. Use it wherever the per-agent section says so.
- **API key.** For clients that send a static header. First check whether `SUPERBOOKS_API_KEY` is already set in the environment; if it is, use it and do not ask. Otherwise ask the user ONCE: "Please create a SuperBooks API key at https://app.superbooks.io/settings/developer (choose the narrowest preset that fits, Read Only is fine to start) and paste it here." Keys start with `sb_`. Store it in the environment as `SUPERBOOKS_API_KEY` (for example in the user's shell profile or the project's untracked `.env`), reference it from config files as an environment variable where the client supports that, and never write the key's value into a file that is committed.

Never embed a key in this conversation's output, in source code, or in a committed config file.

## 3. Register the MCP server in your agent

Use the section for the agent you are. Every section points at the same server:

```text
https://api.superbooks.io/mcp
```

### Claude Code

**Add the SuperBooks server.** Run this in any project. Claude Code stores the server in your user settings, so it is available everywhere.

```bash
claude mcp add --transport http superbooks https://api.superbooks.io/mcp
```

**Sign in.** Inside Claude Code run /mcp, pick superbooks and choose Authenticate. A browser tab opens the SuperBooks consent screen; approve the scopes and come back. If the agent cannot open a browser, add the server with a key instead:

```bash
claude mcp add --transport http superbooks https://api.superbooks.io/mcp \
  --header "Authorization: Bearer $SUPERBOOKS_API_KEY"
```

### Codex

**Add the SuperBooks server.** Registers the remote server in Codex's global config.

```bash
codex mcp add superbooks --url https://api.superbooks.io/mcp
```

**Log in.** Opens the SuperBooks consent screen in your browser.

```bash
codex mcp login superbooks
```

### Cursor

**Add the server to Cursor's MCP config.** Global: ~/.cursor/mcp.json. Per project: .cursor/mcp.json in the repository. Merge into an existing mcpServers object if the file already exists.

`~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "superbooks": {
      "url": "https://api.superbooks.io/mcp"
    }
  }
}
```

**Sign in.** Open Settings → MCP. Cursor shows superbooks with a Needs login state; click it to open the SuperBooks consent screen and approve the scopes.

### Windsurf

**Add the server to Windsurf's MCP config.** Windsurf sends a static header, so it wants a key: mint one at https://app.superbooks.io/settings/developer and put its value where $SUPERBOOKS_API_KEY is below. Do not commit this file.

`~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "superbooks": {
      "serverUrl": "https://api.superbooks.io/mcp",
      "headers": {
        "Authorization": "Bearer $SUPERBOOKS_API_KEY"
      }
    }
  }
}
```

### OpenCode

**Add the server to OpenCode's config.** Global: ~/.config/opencode/opencode.json. Per project: opencode.json in the repository. OpenCode expands {env:NAME} from your shell, so export SUPERBOOKS_API_KEY (a key from https://app.superbooks.io/settings/developer) and the file never holds the secret.

`~/.config/opencode/opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "superbooks": {
      "type": "remote",
      "url": "https://api.superbooks.io/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:SUPERBOOKS_API_KEY}"
      }
    }
  }
}
```

### VS Code and GitHub Copilot

**Add the server to the workspace.** Create or extend .vscode/mcp.json in the repository (or add it to your user settings for every workspace).

`.vscode/mcp.json`:

```json
{
  "servers": {
    "superbooks": {
      "type": "http",
      "url": "https://api.superbooks.io/mcp"
    }
  }
}
```

**Start the server and sign in.** Run the command MCP: List Servers, pick superbooks and choose Start. VS Code opens the SuperBooks consent screen; approve the scopes.

### Any other MCP-capable agent

Add a remote (Streamable HTTP) MCP server named `superbooks` at `https://api.superbooks.io/mcp`. If your client supports OAuth for remote servers, add it with no headers and complete the sign-in when prompted. If it only supports static headers, add `Authorization: Bearer <value of SUPERBOOKS_API_KEY>` using your client's environment-variable substitution so the key is not written into the file.

## 4. Install the SDK (Node.js or Python projects only)

Skip this step if the project is neither. Do not add a dependency to a project that has no use for it.

**Node.js / TypeScript.** Install with the project's package manager (`npm install`, `pnpm add`, `yarn add` or `bun add`):

```bash
npm install superbooks
```

Minimal client, reading the key from the environment:

```typescript
import { SuperBooks } from "superbooks";

const sb = new SuperBooks({ apiKey: process.env.SUPERBOOKS_API_KEY });
const { data } = await sb.transactions.list({ limit: 10 });
```

**Python.**

```bash
pip install superbooks
```

```python
import os
from superbooks import SuperBooks

sb = SuperBooks(api_key=os.environ["SUPERBOOKS_API_KEY"])
transactions = sb.transactions.list(limit=10)
```

The SDKs need an API key (step 2); they do not use OAuth. Both default to `https://api.superbooks.io`.

## 5. Verify

Call the `team_get` MCP tool through the connection you just configured. It takes no arguments and returns the current team's profile (name, base currency, country). Success is a response containing a team name. If the tool is missing from the list, the credential's scopes do not include `teams.read`; if the call returns 401, the credential was not accepted and the sign-in or the key needs redoing.

If you configured an API key and want to check it without an MCP client, run:

```bash
curl -sS -o /dev/null -w "%{http_code}\n" https://api.superbooks.io/mcp \
  -H "Authorization: Bearer $SUPERBOOKS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"agent-setup","version":"1.0.0"}}}'
```

A `200` means the key is accepted; a `401` means it is not.

Rate limit: 120 requests per minute per credential. A `429` carries a `Retry-After` header; wait that long and retry.

## 6. Tell the user what happened

Print a short message in this shape, filling in what you actually did:

```text
SuperBooks is connected to <agent name>.

Installed:
- MCP server "superbooks" -> https://api.superbooks.io/mcp (<OAuth | API key from SUPERBOOKS_API_KEY>)
- <superbooks SDK in package.json | superbooks in requirements | no SDK: not a Node.js or Python project>

Verified: team_get returned team "<team name>".

You still need to:
- <Restart the editor | run /mcp and Authenticate | nothing>
- Keep SUPERBOOKS_API_KEY out of version control.

Docs: https://docs.superbooks.io/  FAQ: https://docs.superbooks.io/faq
```

## Resources

- Documentation: https://docs.superbooks.io/
- FAQ: https://docs.superbooks.io/faq
- llms.txt: https://docs.superbooks.io/llms.txt
- Quickstart: https://docs.superbooks.io/quickstart
- Authentication and scopes: https://docs.superbooks.io/authentication
- Connecting AI clients by hand: https://docs.superbooks.io/mcp
- API reference: https://docs.superbooks.io/api-reference/transactions
- Rate limits: https://docs.superbooks.io/rate-limits
- TypeScript SDK: https://docs.superbooks.io/sdks/typescript
- Python SDK: https://docs.superbooks.io/sdks/python
- Status page: https://status.superbooks.io/
- Support: mailto:support@superbooks.io

This file: https://docs.superbooks.io/agent-setup/prompt.md