# Connect Claude Code

> Add the Tabba MCP server to Claude Code and authenticate with OAuth.

Source: https://www.tabba.io/developers/mcp/claude-code

Claude Code talks to remote MCP servers over HTTP. One command adds Tabba,
and the OAuth flow opens in your browser. The browser step cannot be left
out: see [Not from CI](#not-from-ci) if that is where you were heading.

## Add the server [#add-the-server]

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

Then start Claude Code and run `/mcp`. Pick **tabba** and authenticate. The
browser opens Tabba: sign in if you are asked to, pick the company on the
consent page, and choose **Approve**.

Check that it is there:

```bash
claude mcp list
```

`tabba` should be listed as connected. If it is listed as needing
authentication, the entry is written and you have not completed `/mcp` yet.

## Scope it to a project or to yourself [#scope-it-to-a-project-or-to-yourself]

Claude Code stores a server in one of three scopes. These are Claude Code's
own, and have nothing to do with the scope of a Tabba token.

| Scope                 | Stored in                                   | Reaches                     |
| --------------------- | ------------------------------------------- | --------------------------- |
| `local` (the default) | `~/.claude.json`, under this project's path | Only you, only this project |
| `project`             | `.mcp.json` in the repository root          | Everyone who clones it      |
| `user`                | `~/.claude.json`                            | Only you, every project     |

Tabba is about a company, not about a repository, so the user scope is
usually the right one:

```bash
claude mcp add --transport http --scope user tabba https://www.tabba.io/api/mcp
```

> [!NOTE]
> **The entry holds no secret**
>
> The entry records the URL. The token is kept by Claude Code, and each
> person who authenticates gets their own, as themselves, on the company
> they pick.

> [!WARNING]
> **Project scope commits a file**
>
> `--scope project` writes `.mcp.json` into the repository. Every
> collaborator is then asked to authenticate, each with their own Tabba
> sign-in. A collaborator with no access to a connected company in Tabba has
> nothing to approve. A run with no person at a browser loads the entry and
> never connects.

## Not from CI [#not-from-ci]

The consent page takes a signed-in browser session, and Tabba accepts no
other MCP credential: no key, no header, no long-lived token. A build agent,
a scheduled runner or a `claude -p` job on a server cannot connect.

Point that work at the [REST API](/developers/api). It authenticates with a
key on `/api/v1`, reaches the same Sales data, and uses the same error codes.

## Verify it works [#verify-it-works]

```
> What work do I have open?
```

Claude Code shows the tools it called. A call to `get_my_work` that answers
with your real lines means the token is live and holds `mcp:read`.

## What it answers by default [#what-it-answers-by-default]

```
> Which customers do I have?
```

You get your customers: the ones billed by the invoices and recurring series
you hold a place on, not every customer of the company. The answer opens by
saying so. The whole company is an admin's to ask for. See
[Auth and scopes](/developers/mcp/auth).

## Two prompts come with it [#two-prompts-come-with-it]

The server's two prompts appear in Claude Code as commands: one turns a
contract into the invoicing it calls for, one walks the monthly close. Each
is worded from the tools your connection has, and each puts a plan to you
before anything is committed.

## Troubleshooting [#troubleshooting]

* **The server needs authentication.** Run `/mcp`, select **tabba** and
  authenticate. A session with no person at a browser cannot.
* **The write tools are missing.** `/mcp` shows the tools of each server. An
  admin is offered 17 tools on a connection that reads, 26 on one that may
  write and 29 on one that may issue. A standard user is offered 13, and 15
  with `plan_register_work` and `commit` on a connection that may write. If
  the count is lower than your role allows, the token's scope is narrower
  than you expected: authenticate again.
* **A commit times out.** A request to the server runs for at most 60
  seconds. Call `commit` again with the same token. A plan is applied once:
  the second call resumes what the first did not finish, or answers its
  result. While the first is still running the answer is
  `COMMIT_IN_PROGRESS`: wait a few seconds and call again.
* **A tool's output is too long for Claude Code.** A list of invoices in a
  busy company can exceed the limit Claude Code puts on a tool's output.
  Narrow the question (by customer, or by status), or raise that limit in
  Claude Code's settings.
* **Two entries with one name.** A local entry is used before a project
  entry, and a project entry before a user entry. `claude mcp get tabba`
  shows the one in use.

## Remove it [#remove-it]

```bash
claude mcp remove tabba
```

Add `--scope user` or `--scope project` if that is where you put it. Removing
the entry does not revoke anything in Tabba. Revoke the access under **Claude
and other AI clients** on your profile settings in Tabba, with **Revoke
access**. That ends every AI client connection of yours, not only this one.