# Set up Ringbook for an AI agent

You are an AI agent. The user wants you to connect to Ringbook, their bookkeeping app, through MCP (Model Context Protocol). Follow these steps and tell the user in plain words what you are doing.

Ringbook MCP server: https://backend.ringbook.io/mcp
Transport: Streamable HTTP. Sign-in: OAuth, in the user's browser.

## Rules

- Never ask the user to paste a password, a sign-in code or a Ringbook token (it starts with rb_mcp_) into the chat, and never write a token into a command or a config file yourself.
- Change only your own MCP settings, and only the "ringbook" entry. Read a config file before you change it; if it does not parse, stop and tell the user.
- Show each command and wait for the user's OK before you run it.
- Do not say Ringbook is connected until step 3 succeeds.

## 0. Check for an existing "ringbook" server

Look first: `claude mcp get ringbook` (Claude Code), `codex mcp get ringbook` (Codex), or the "ringbook" entry in ~/.cursor/mcp.json (Cursor). If one exists, show it to the user and ask before replacing it. An old entry that sends an Authorization header stops the browser sign-in from starting, so replace it rather than keep it. To remove: `claude mcp remove ringbook --scope user` or `codex mcp remove ringbook`.

## 1. Add the server

Find out which app you are running in and use its step. If you cannot change your own settings, give the user the steps instead.

- Claude Code: run `claude mcp add --transport http --scope user ringbook https://backend.ringbook.io/mcp`
- Codex: run `codex mcp add ringbook --url https://backend.ringbook.io/mcp`
- Cursor: in ~/.cursor/mcp.json, add `"ringbook": { "url": "https://backend.ringbook.io/mcp" }` inside "mcpServers" and leave the other servers as they are. If the file does not exist, create it as `{ "mcpServers": { "ringbook": { "url": "https://backend.ringbook.io/mcp" } } }`.
- VS Code: run `code --add-mcp '{"name":"ringbook","type":"http","url":"https://backend.ringbook.io/mcp"}'` (on Windows, quote the JSON for your shell, or ask the user to use the "Add to VS Code" button on the Ringbook page)
- claude.ai or Claude Desktop (the user does this): Customize → Connectors → Add → Add custom connector (https://claude.ai/customize/connectors), then paste the server address.
- ChatGPT (the user does this): Customize → Plugins → Add → Add custom MCP server (https://chatgpt.com/plugins), paste the server address, keep OAuth and choose Create as a plugin.
- Grok (the user does this): open grok.com/connectors, choose New Connector, then Custom, and paste the server address.
- Any other app that supports remote MCP servers: add a server named ringbook with this address and OAuth sign-in.

## 2. Sign in

- Claude Code: the user types /mcp, picks ringbook and chooses Authenticate.
- Codex: run `codex mcp login ringbook`. It opens the sign-in in a browser on the same computer, so it does not work over SSH.
- Cursor, VS Code and the chat apps ask the user to sign in the first time they use the server.

On the Ringbook page the user picks the organizations and the access level for each (Report, Read or Write), then chooses Allow. Your app may need a restart or a new session before the Ringbook tools appear.

## 3. Check the connection

Call the get_my_access tool and tell the user which organizations you can reach and at which level. If it fails, report the error message as it is; do not guess the cause.

If the Ringbook tools are not available in this session yet, say "Ringbook is added but not verified yet", and tell the user to finish the sign-in, restart the app or open a new session, then ask you to "check my Ringbook connection".

## Without a browser (servers, CI, scheduled jobs)

OAuth needs a browser. Without one, the user creates a personal access token in Ringbook (Connect to Ring → AI agents → Create token) and stores it in the environment variable RINGBOOK_MCP_TOKEN themselves. The server expects the header `Authorization: Bearer <token>`; configure your app to read it from that variable, not to contain the token itself.

- Codex: `codex mcp add ringbook --url https://backend.ringbook.io/mcp --bearer-token-env-var RINGBOOK_MCP_TOKEN`
- Other apps: use the app's own way to fill a header from an environment variable. If it has none, tell the user and stop; the Ringbook page shows ready-made commands when the token is created.

## After you connect

- Where journal entries you create go is the organization's AI posting mode (`get_organization_info` returns `mcpWriteMode`): drafts a person reviews (the default), the user's Input page for the day, or automatic posting. You can change it with `set_mcp_write_mode`, but only when the user explicitly asks you to.
- `approve_journals` and `approve_ring` sign off as the user, exactly like Approve in Ringbook. Find the journals with `search_transactions`, show the user the list and approve only after they agree. Nobody can approve a journal or Ring they created, and an approval cannot be removed over MCP.
- Full guide for people: https://ringbook.io/mcp
