> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sorraia.app/llms.txt
> Use this file to discover all available pages before exploring further.

# AI assistants (MCP)

> Connect Claude Code, Cursor or Codex to Sorraia over MCP with an API key. The assistant reads your sites, forms, submissions, bookings and orders.

Sorraia runs an [MCP](https://modelcontextprotocol.io) server, so an AI assistant can read
your Sorraia data and answer questions about it: which forms got the most submissions this
week, who booked for tomorrow, what an order's shipping address was.

| | |
| - | - |
| URL | `https://api.sorraia.app/mcp` |
| Transport | Streamable HTTP |
| Sign-in | an API key, sent as `Authorization: Bearer sor_live_…` |
| Access | read-only: no tool changes anything |
| Plans | every paid plan, like the API |

## Connect

Create a key for the assistant in the dashboard under **Settings → Integrations** (the
**Programmatic API access** section); see [Authentication](https://docs.sorraia.app/authentication.md). Give each
assistant its own key. The assistant sees only the tools the key's scopes allow.

### Claude Code

```bash theme={null}
claude mcp add --transport http sorraia https://api.sorraia.app/mcp \
  --header "Authorization: Bearer sor_live_xxxxxxxx"
```

### Cursor

In `~/.cursor/mcp.json`, or `.cursor/mcp.json` in a project, with the key in an environment
variable:

```json theme={null}
{
  "mcpServers": {
    "sorraia": {
      "url": "https://api.sorraia.app/mcp",
      "headers": { "Authorization": "Bearer ${env:SORRAIA_API_KEY}" }
    }
  }
}
```

### Codex

In `~/.codex/config.toml` (also read by the ChatGPT desktop app), with the key in an
environment variable:

```toml theme={null}
[mcp_servers.sorraia]
url = "https://api.sorraia.app/mcp"
bearer_token_env_var = "SORRAIA_API_KEY"
```

### Other clients

Any MCP client that can send a fixed `Authorization` header to a remote (Streamable HTTP)
server connects the same way. claude.ai, the Claude desktop and mobile apps and ChatGPT
connect through an OAuth sign-in, which this server does not offer yet. Where a Claude
organization can add a connector with a request header (a beta Anthropic offers to some
organizations), the same header works, and everyone in that organization reaches Sorraia
with that one key.

## Tools

| Tool | Returns | Scope |
| - | - | - |
| `list_sites` | Your sites that have a form, calendar or shop the key can read, with each site's verification status | `read:forms`, `read:calendars` or `read:ecommerce` |
| `list_forms` | Forms, most recently updated first. `site_id` narrows to one site | `read:forms` |
| `list_submissions` | Form submissions, newest first. `form_id` narrows to one form | `read:submissions` |
| `get_submission` | One submission, by `id` | `read:submissions` |
| `list_calendars` | Booking calendars, most recently updated first. `site_id` narrows to one site | `read:calendars` |
| `list_bookings` | Bookings, newest first. `calendar_id` narrows to one calendar | `read:bookings` |
| `get_booking` | One booking, by `id` | `read:bookings` |
| `list_shops` | Shop widgets, most recently updated first. `site_id` narrows to one site | `read:ecommerce` |
| `list_orders` | Orders, newest first. `shop_id` narrows to one shop | `read:orders` |
| `get_order` | One order, by `id` | `read:orders` |

A list returns `items`, `total` and `next_cursor`; the assistant passes `next_cursor` back as
`cursor` for the next page, and `null` means the last page. A `list_submissions` result:

```json theme={null}
{
  "items": [
    {
      "id": 4812,
      "formId": 37,
      "createdAt": "2026-11-14T09:12:03.000Z",
      "untrusted": {
        "sourceDomain": "www.example.com",
        "answers": [
          { "field": "name", "value": "Ana Silva" },
          { "field": "email", "value": "ana@example.com" }
        ]
      }
    }
  ],
  "next_cursor": "20",
  "total": 312
}
```

## What the assistant sees

* Your account's data, never more than the REST API returns for the same key. Compared with
  the dashboard, these are left out:

  * archived sites and widgets, and their records;
  * submissions held as spam, and bookings flagged as spam;
  * forms, with their submissions, that sit on a site belonging to another account (for
    example a form moved into an organization from a personal site);
  * cart orders whose items are not all on one of your live sites (a cart that mixes sites, or
    holds a product with no site).

  So a count or total the assistant gives can be lower than the dashboard's. Booking
  video-call links are left out too.
* Nothing on a site that uses HIPAA mode. An account with a HIPAA Business Associate Agreement
  record at Sorraia, whatever its status (signed, pending, winding down or ended), cannot use
  the MCP server: every tool answers with a refusal. Use the dashboard for that data.
* What visitors typed (form answers, names, emails, notes, addresses) comes back inside an
  `untrusted` object, and the server tells the assistant to treat those values as data, never
  as instructions. Invisible characters are removed from all text.
* Long values are cut. A record that was cut carries `"truncated": true`, and a page holds
  fewer items when its records are large.

## Keys and access

* Give each assistant its own key, so you can revoke one without touching the others.
* A key created in an organization reads every site in that organization, including client
  sites you manage for others. A personal key reads only your personal account.
* A key you add where others share it (a Claude organization's connector settings, a Cursor
  project file in a shared repository) lets everyone there reach Sorraia with it.
* Each tool call counts against the key's API rate limit, shared with the REST API (1,000
  requests an hour). Over it, the tool answers with a sentence asking to try later.
* Sorraia records every tool call that runs: the key, the tool and the ids it was given, never
  the data it returned. A call refused for its arguments or for the rate limit reads nothing
  and is not recorded or counted.

## Privacy

When you connect an AI assistant, what it reads is sent to that assistant's provider at your
request, under your agreement with them.

## Errors

| Status | When |
| - | - |
| 401 | The key is missing, unknown, revoked or expired. |
| 402 | The key's account is on the Free plan. |
| 403 | The request came from a browser origin that may not call the server. |
| 405 | A method other than POST was sent to `/mcp`. |

Inside a call, a refusal (a record that does not exist or that the key cannot read, the rate
limit, an account with a HIPAA agreement record) comes back as a tool error with a plain
sentence.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.