# Connect an AI agent over MCP

> Add the CMS to Claude, Cursor, VS Code or any MCP client, sign in or use an agent key, test the connection and revoke it.

Source: https://docs.bifrostorbit.com/cms/developers/connect-an-ai-agent/

The CMS has an MCP (Model Context Protocol) server, so AI assistants such as Claude can find, read and draft content the way an editor does. The address is:

```text
https://app.bifrostorbit.com/cms/mcp
```

It uses the Streamable HTTP transport. The same address, with a copy button, is on **Configuration › AI agents**. For what an editor sees and how drafts are reviewed, see [Let an AI assistant draft content](https://docs.bifrostorbit.com/cms/editors/ai-assistants/).

## Before you start

1. Open **Configuration › AI agents** on the website the agent should work on.
2. Check the switches under **Access**:
   - **Allow AI agents in the organisation** is on by default. Turning it off stops every agent on every website at once. It needs someone who can change the organisation's settings.
   - **Allow AI agents on this website** is off until an Administrator turns it on.
   - **Allow drafts in production** is off by default. Agents can then read Production but only draft in other environments, such as Staging.
3. You need to be able to edit content on the website. Agents never get more rights than the person they act for.

While either of the first two switches is off, every request is refused with *AI agents are switched off for this website*.

## Sign in or use a key

There are two ways to connect. Both act for a person, within that person's rights, and both are capped to the agent's short list of drafting permissions.

| | Sign in | Agent key |
| --- | --- | --- |
| How it works | The assistant opens a browser, you sign in to Bifröst Orbit the way you always do, choose the website and select **Allow**. | You create a key starting with `cms_ag_` and put it in the client's settings as a bearer token. |
| Best for | Assistants that support MCP sign-in: Claude, Claude Code, Cursor, VS Code. | Clients that cannot sign in, scripts and scheduled jobs. |
| Regions | Every region. | Every region, or only the regions you tick. |
| How long it lasts | Until you revoke it, as long as it is used at least once every 30 days. The client renews it by itself. | 7, 30 or 90 days, or 1 year. |
| Listed as | **Signed in** | **Personal** or **Automation** |

Sign-in uses OAuth with PKCE. The client finds the sign-in details by itself from the MCP address, so there is nothing to copy except the address.

### Create an agent key

1. In **Configuration › AI agents**, under **Keys**, select **New agent key**.
2. Give it a **Name**, such as `Claude`. The name appears on everything the agent drafts.
3. Choose the **Kind**:
   - **Personal, acts for me**: for your own assistant. Anyone who can edit content can create one.
   - **Automation, scheduled jobs**: for jobs that run with no one present. Only people who manage API keys can create one. It still acts with the rights of the person who created it.
4. Choose when it **Expires after**.
5. If the website has more than one region, tick the **Regions it may change**. None ticked means every region. The agent can still read the others.
6. Select **Create key** and copy the key. This is the only time it is shown. If it is lost, revoke it and create another.

Keep the key out of source control and shared files. Anyone with the key can draft as you.

## Connect your client

The quickest way is on the **AI agents** screen under **Configuration**: **Add to Cursor** and **Add to VS Code** open the app and ask to add the server, and **Copy Claude Code command** copies the command for a terminal. They use the address of the CMS you are in, so they work the same on staging. The steps below do the same by hand.

Use `cms-orbit` as the server name, or any name you like.

### Claude (web and desktop app)

Add a custom connector in Claude's connector settings and paste the MCP address. Claude opens the sign-in page. Sign in, choose the website and select **Allow**.

Custom connectors sign in; they do not take an agent key. To use a key in the Claude desktop app instead, run the open source `mcp-remote` bridge from `claude_desktop_config.json`. It needs Node.js.

```json
{
  "mcpServers": {
    "cms-orbit": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://app.bifrostorbit.com/cms/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer cms_ag_your_key"
      }
    }
  }
}
```

Restart the app after saving the file.

### Claude Code

**Copy Claude Code command** on the **AI agents** screen gives you the first command below. To sign in, add the server and then run `/mcp` inside Claude Code and choose it to authenticate:

```bash
claude mcp add --transport http cms-orbit https://app.bifrostorbit.com/cms/mcp
```

To use an agent key instead:

```bash
claude mcp add --transport http cms-orbit https://app.bifrostorbit.com/cms/mcp \
  --header "Authorization: Bearer cms_ag_your_key"
```

Add `--scope user` to make it available in every project, rather than only the current one.

### Cursor

Choose **Add to Cursor** on the **AI agents** screen, confirm in Cursor, and sign in when it first connects. To set it up by hand, add the server to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in a project. To sign in, give only the address; Cursor asks you to sign in when it first connects:

```json
{
  "mcpServers": {
    "cms-orbit": {
      "url": "https://app.bifrostorbit.com/cms/mcp"
    }
  }
}
```

To use an agent key, add a header:

```json
{
  "mcpServers": {
    "cms-orbit": {
      "url": "https://app.bifrostorbit.com/cms/mcp",
      "headers": {
        "Authorization": "Bearer cms_ag_your_key"
      }
    }
  }
}
```

Do not commit a project file that contains a key.

### VS Code

Choose **Add to VS Code** on the **AI agents** screen, confirm in VS Code, and sign in when the server starts. To set it up by hand, add the server to `.vscode/mcp.json` in your workspace. To sign in, give only the type and address; VS Code asks you to sign in when the server starts:

```json
{
  "servers": {
    "cms-orbit": {
      "type": "http",
      "url": "https://app.bifrostorbit.com/cms/mcp"
    }
  }
}
```

To use an agent key without writing it in the file, let VS Code ask for it once and store it securely:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "cms-orbit-key",
      "description": "CMS Orbit agent key",
      "password": true
    }
  ],
  "servers": {
    "cms-orbit": {
      "type": "http",
      "url": "https://app.bifrostorbit.com/cms/mcp",
      "headers": {
        "Authorization": "Bearer ${input:cms-orbit-key}"
      }
    }
  }
}
```

### Any other MCP client

Any client that supports the Streamable HTTP transport works:

- **Address:** `https://app.bifrostorbit.com/cms/mcp`
- **Sign-in:** OAuth 2.1 with PKCE (S256) and dynamic client registration. An unauthenticated request gets `401` with a `WWW-Authenticate` header pointing at the sign-in details. The client must return to an `https` address, or to `http` on `localhost`.
- **Key:** send `Authorization: Bearer cms_ag_…` on every request.
- The server answers each request with plain JSON and keeps no session between requests.

## Which website, environment and region

- **Website:** each key or sign-in belongs to one website. A key belongs to the website it was created on; when signing in you pick it under **Which website?**. To work on two websites, connect twice.
- **Environment:** tools work in Staging unless the agent names another environment. Drafting in Production also needs **Allow drafts in production**.
- **Region and language:** tools use the default region and its default language unless the agent names others, such as region `de` and locale `de-DE`.

Ask the agent to run `list_scopes` to see every environment, region and language, and which ones it may change. See [MCP tools](https://docs.bifrostorbit.com/cms/developers/mcp-tools/) for every tool.

## Test the connection

In the assistant, ask something that reads only, such as *"List the scopes you can work in"* or *"Find the page at /products/hiking-boots"*. The assistant should call `list_scopes` or `search_content` and show the result.

With a key, you can also test from a terminal. This lists the tools without changing anything:

```bash
curl https://app.bifrostorbit.com/cms/mcp \
  -H "Authorization: Bearer cms_ag_your_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

A working key answers with a list of tools. On **Configuration › AI agents**, the key's **Last used** column then shows when it was last used.

## Revoke access

On **Configuration › AI agents**, open the menu at the end of the key's row and select **Revoke**. The agent is refused from its next request. Revoking cannot be undone; create a new key or sign in again to reconnect.

- Signed-in connections are listed with the badge **Signed in**, so you disconnect them the same way.
- You can revoke your own keys and connections. People who manage API keys see every key on the website and can revoke any of them.
- To stop every agent at once, turn off **Allow AI agents on this website**, or **Allow AI agents in the organisation** for every website.
- If the person a key acts for is deactivated, all their keys and connections stop working.
- A new key, or signing in again, is a new connection. An agent can discard only the drafts and uploads it made through its own connection, so it cannot tidy up what an old one left. A person can delete those. See [MCP tools](https://docs.bifrostorbit.com/cms/developers/mcp-tools/).

## Troubleshooting

| What you see | What it means |
| --- | --- |
| `401` *An agent key or sign-in is required* | No bearer token was sent, or it is not a CMS agent key or sign-in. Check the header is `Authorization: Bearer cms_ag_…`. |
| `401` *This agent key is not valid* | The key is mistyped, revoked or expired, or a signed-in connection has lapsed. Create a new key or sign in again. |
| `403` *AI agents are switched off for this website* | **Allow AI agents on this website** or **Allow AI agents in the organisation** is off. |
| `403` *The person this agent acts for no longer has access* | The person's account was deactivated. Someone with access needs to connect instead. |
| `429` *Too many requests from this agent* | Each key or connection may make 60 requests a minute. The `Retry-After` header says how many seconds to wait. |
| `413` *The request is too large* | A request may be at most 5 MB. Images for `upload_media` may be at most 3 MB. |
| `406` *Not Acceptable* | The client did not send `Accept: application/json, text/event-stream`. MCP clients do this for you; add it when testing with `curl`. |
| *This app is not registered with the CMS* on the sign-in page | The client's registration was lost. Remove the server from the client and add it again. |
| *You cannot edit any website, so there is nothing to connect it to* | You cannot edit content on any website. Ask an Administrator for a role that can edit. |
| The website shows *AI agents are off* when signing in | You can still allow the connection, but it is refused until an Administrator turns agents on. |
| A tool answers *Your role (…) cannot perform "content:update"* | The agent is reading a scope it may not change: Production without **Allow drafts in production**, a region the key is not limited to, or something the person cannot edit. |
| A tool answers *Environment not found*, *Region not found* or *Locale not found* | The key given does not exist on this website. Run `list_scopes` for the right keys. |

For errors that tools return while drafting, see [Limits and errors](https://docs.bifrostorbit.com/cms/developers/mcp-tools/).