# The MCP server (/docs/agents/mcp)

`https://www.obelism.studio/mcp` is one [MCP](https://modelcontextprotocol.io) server for Obelism: Improve's, Content's and Numbers' tools, and those of your account itself, behind one sign-in. An agent connected to it works as you, in every Organization you belong to, as far as your role in each allows.

## Connecting [#connecting]

Add the server to your client as a remote (Streamable HTTP) server. For Claude Code:

```bash
claude mcp add --transport http obelism https://www.obelism.studio/mcp
```

[Agent setup](https://www.obelism.studio/agent-setup.md) has Claude on the web and Desktop, Codex, Cursor, VS Code, Windsurf, OpenCode and any other client.

The first time the client reaches the server, it opens a page on www.obelism.studio in your browser:

1. Sign in, if you aren't. Your email address has to be verified.
2. **Connect**, with the app's name, shows what it asked for: reading, or reading and changing. It shows the app's domain when it was verified, and warns you when the app only named itself or sends you back to your own computer.
3. **Allow access** connects it. The app now has your access in every Organization you belong to.

Signing in is OAuth 2.1. Clients register themselves (Dynamic Client Registration, or a Client ID Metadata Document) and find everything from the server's `401` and its `/.well-known` documents: there's nothing to configure but the URL.

## Read and write [#read-and-write]

The app asks for one or both scopes, and the consent page shows which:

| Scope           | The app gets                                                                                  |
| --------------- | --------------------------------------------------------------------------------------------- |
| `obelism:read`  | The tools that only read: listing and reading tests, flags, entries, reports, members, Spaces |
| `obelism:write` | Every tool, reading included: creating, changing, publishing and deleting                     |

The split follows the HTTP method of the operation behind each tool: a `GET` reads, anything else writes. So a few tools that only look also need write, such as Content's `previewEntry` and Improve's `refreshTestResults`. A client that asks for neither scope gets both.

<Callout type="info">
	The scope narrows what the app may do; your role still decides the rest. A
	reader's agent with `obelism:write` still can't change anything. See [What an
	agent may do](/docs/agents/permissions).
</Callout>

## Tools [#tools]

The server's tools are each product's agent API operations, read from that product's OpenAPI spec (`/openapi.json`), so a new operation in a product shows up on the server without a change here.

- **A product's tools carry its name**: `improve_listTests`, `improve_createTest`, `content_listEntries`, `content_saveEntry`, `content_publishEntry`, `numbers_getReport`.
- **Your account's tools have no prefix**, including `listMembers`, `inviteMembers`, `updateMember`, `removeMember`, `listInvites`, `acceptInvite`, `createOrganization`, `createSpace`, `renameSpace`, `transferSpace`, `updateSecurity`, `listConnections`, `saveConnection`, `deleteConnection` and `updateProfile`.
- **Never offered**: deleting an Organization or a Space, signing out and changing your password. A person does those on www.
- Each tool is marked read-only, destructive or idempotent where it is, so a client can ask you before running one.

There are about 140 tools in all; with `obelism:read`, about 55. A client that copes badly with that many can use [a product's own server](/docs/agents#each-products-own-server) instead.

<Callout type="warn">
	Media's tools aren't on this server yet. Connect
	`https://media.obelism.studio/mcp` for files, folders and shares.
</Callout>

The server also tells the agent how the products fit together: start with a product's `listOrganizations` and `listSpaces`, use the same Organization, Space and environment ids across products, and work in `production` unless you say otherwise.

### Working across products [#working-across-products]

Tools of different products combine on the same ids. An A/B test on a block of a Content page, for example:

1. `improve_createTest` creates the test in the Space's environment.
2. `content_saveEntry` places it on the page as an A/B test block, with the blocks for each variant.
3. `improve_getTestResults` and `numbers_listEvents` read how it does.

## How long access lasts [#how-long-access-lasts]

An app's access token lasts an hour and is renewed by the app as it goes. Access ends after **30 days without use**, after 90 days at most, when you disconnect the app, or when you change or reset your password. Signing in again connects it anew.

[Agents](https://www.obelism.studio/agents) on www lists the apps connected to this server, with **Disconnect**. Production and each preview deployment of www are separate servers: a sign-in on one doesn't work on another.

## Errors and limits [#errors-and-limits]

- A product's error comes back as the tool's result, marked as an error: its [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem JSON, with a `code` (`insufficient_role`, `product_disabled`, `production_protected`, `conflict`, …) and a `hint` on what to change.
- A product that can't be reached answers with a message to try again later.
- Content, Numbers and Media allow 300 agent calls a minute per person; a `429` says when to try again.
- Invites are limited to 50 addresses a request, 10 requests an hour per Organization and 3 emails a day per address.

## Not for sites [#not-for-sites]

The server takes only the access tokens its own sign-in hands out. API tokens (Improve's, Content's, Numbers') are for your sites and servers and don't work here, and an agent's access doesn't work as an API token.