# Connect an AI assistant

Oscar has an MCP server (Model Context Protocol). Connect an AI assistant
to it, and the assistant can read your books and do your part of the work
there: find an invoice, show what a customer still owes, record and issue an
invoice, upload a receipt. It acts with your permissions, and every call goes
through the same API and the same checks as the app.

## The server

| Address                                    | What it gives                                             |
| ------------------------------------------ | --------------------------------------------------------- |
| `https://oscaraccountant.com/mcp`          | Every tool that your permissions allow, reads and writes  |
| `https://oscaraccountant.com/mcp/readonly` | The read tools only. The assistant cannot change anything |

The server is on the same host as the app that you sign in to. The transport
is Streamable HTTP.

## Connect

### Claude

In Claude, add a custom connector with the server address. Claude opens the
Oscar sign-in page, then the consent page.

### ChatGPT

In ChatGPT, add a connector with the server address (this can need the
developer mode of ChatGPT) and choose OAuth. ChatGPT opens the Oscar
sign-in page, then the consent page.

### Cursor

Add the server to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "oscar": { "url": "https://oscaraccountant.com/mcp" }
  }
}
```

Cursor asks you to sign in when it first connects.

### Claude Code

```bash
claude mcp add --transport http oscar https://oscaraccountant.com/mcp
```

Then run `/mcp` in Claude Code and sign in.

## Sign-in and consent

The assistant signs you in with OAuth 2.1:

1. The assistant opens the Oscar sign-in page in your browser.
2. The consent page shows the name of the assistant, its app ID (the
   `client_id`), where it sends you back to, and what it asks for: `read`, or
   `read` and `write`. An assistant that asks for no scope gets `read` only.
   For an app that registered itself, the page says so and shows no logo:
   check the app ID. It also warns when the app sends you back to a host
   that is not its own.
3. **You choose one organization.** The connection reaches the companies of
   that organization only. To reach a second organization, add a second
   connection.
4. You approve, and the assistant is connected.

When the same assistant asks again with nothing changed, Oscar does not
show the consent page again.

See and revoke your connections under "Connected apps" in the security
settings of your account. A change of your password or of your two-factor
authentication revokes every connection.

## With an API key instead

An assistant that can send a fixed header can use an API key of your
organization instead of OAuth:

```http
Authorization: Bearer osk_live_...
```

For example in Claude Code:

```bash
claude mcp add --transport http oscar https://oscaraccountant.com/mcp \
  --header "Authorization: Bearer osk_live_..."
```

The key reaches its own organization, with its scopes. See
[Authentication](/docs/api/guides/authentication).

## What the assistant sees

- **Only the tools you may use.** The server lists the tools that your role,
  the scopes of the connection, and the client capabilities of your company
  allow. A connection with the `read` scope, or to `/mcp/readonly`, has no
  write tools. The list is a guide: the API still checks every call.
- **Call `list_companies` first.** Every other tool takes a `company_id`.
- **A write tool takes an `idempotency_key`.** The same key and the same
  arguments return the first result instead of running twice.
- **An error has a stable code**, as in the API: for example `not_found`,
  `validation_error`, `insufficient_scope`, `human_actor_required`.
- **A human judgement** (an exemption, a classification of money received,
  the reopening of a period) is never run by the assistant. It calls
  `propose_judgement`, and a person confirms the proposal in the Oscar app.
  See [Human judgements](/docs/api/guides/human-judgements).

The [tool reference](/docs/mcp/tools) lists every tool.

## What only your accountant does

Your accountant keeps the books with Oscar. Some work is theirs, and a
client connection has no tools for it:

- **VAT returns**: preparing, amending and filing them.
- **Period closing**: closing a month or a year, and reopening one.
- **The set-up of the books**: the chart of accounts, the VAT codes, the
  policies of the company.
- Voiding a posted invoice, and recording accounting events.

Ask your accountant for these. What else a client may do is set by Oscar
for each company, for example the import of bank statements.