Connect AI assistants with MCP

You can let an outside AI assistant, such as Muse, Claude Code, or Cursor, look things up in your Spacebrain workspace and suggest changes. You control what it can reach with an access token that you create in Settings → AI Agents. This guide is for workspace owners and admins who want to connect an assistant.

When you finish, your assistant can answer questions from your Spacebrain data, and any change it suggests waits in Orbit until someone approves it.

What is MCP?

MCP (Model Context Protocol) is a common way for AI assistants to connect to other apps. Spacebrain runs an MCP server that gives assistants the same tools Orbit, Spacebrain's built-in assistant, uses. The server address is shown in Settings → AI Agents under How to connect:

https://api.spacebrain.ai/mcp

What an assistant can and can't do

• Look things up straight away. It can search records, list deals, check bookings and tasks, read conversations, and pull reports, within what the token allows.
• Make simple additions straight away, just as Orbit can: create a lead, deal, company, person, note, or task.
• Ask before anything else. Updating or deleting records, moving deals, sending messages, and publishing come back as a proposal with a preview. Nothing changes until someone approves it.
• Stay inside its limits. A token can only use the product areas (called packs) you choose. Tools outside them are hidden from the assistant.
• Never act above Editor. The assistant uses the role of the person who created the token, capped at Editor. It can never do things that need Admin or Owner.
• Never touch billing or people. Assistants can't change subscriptions, buy credits, change payment methods, invite or delete users, or delete or transfer workspaces.

Before you begin

• A paid plan. On the Free plan, the page shows AI agent access is available on paid plans.
• The Owner or Admin role. Other roles see Only workspace owners and admins can create or revoke agent access tokens.
• An assistant that accepts a token in a header, such as Muse, Claude Code, Cursor, or another MCP client that supports "Streamable HTTP" with a custom header.
• A test record, such as a test lead, for your first change.

Create an access token

1. Go to Settings → AI Agents and select Create access token.
2. In Name, say where the token will be used, for example "Muse on my phone" or "Cursor on my laptop".
3. Under Which assistant will use it?, choose Muse, Cursor / Claude Code, Claude, ChatGPT, or Other MCP client.
4. Under Access, choose one:
   • Read only — the assistant can look things up.
   • Read + write — it can also propose changes (you confirm each one in Orbit).
5. To limit the token to certain areas, select Choose specific packs and tick Read and Write for each pack you want. Select Reset to preset to go back.
6. Under Expires, choose In 30 days, In 90 days (the default), In a year, or Never. Spacebrain caps every token at one year, so Never also ends after a year.
7. Select Create token.
8. On Copy your token now, copy the token. Spacebrain shows it only once. Then select Done.

If you try to close without copying, Spacebrain asks: You haven't copied the token. Spacebrain won't show it again. Close anyway? If you lose a token, revoke it and create a new one.

Create one token per assistant and device. Then you can revoke one without affecting the others, and each gets its own Orbit thread.

Connect your assistant

The How to connect section in Settings → AI Agents has a tab for each assistant, with text you can copy. After you create a token, the Next step box shows the same instructions.

Muse

1. Send Muse this message:

   Connect to Spacebrain's MCP server at https://api.spacebrain.ai/mcp. It uses a bearer access token in the Authorization header. Ask me for the token when you need it.

2. Muse asks for an API key or header value in its secure prompt. Paste your token there, not in the chat.

3. Ask a question to check it works, such as "What deals are closing this month?"

Claude Code

Run this in a terminal. Replace <paste your token> with your token:

claude mcp add --transport http spacebrain https://api.spacebrain.ai/mcp --header "Authorization: Bearer <paste your token>"

Start Claude Code and run /mcp to check that spacebrain is connected.

Cursor

Add this to your mcp.json file, with your token in place of the placeholder:

{
  "mcpServers": {
    "spacebrain": {
      "url": "https://api.spacebrain.ai/mcp",
      "headers": { "Authorization": "Bearer <paste your token>" }
    }
  }
}

The server and its tools appear once Cursor reconnects.

Other MCP clients

Use these settings:

• URL: https://api.spacebrain.ai/mcp
• Transport: Streamable HTTP
• Header: Authorization
• Value: Bearer followed by a space and your token

Claude.ai, Claude Desktop, and ChatGPT

These apps add custom connectors by signing in, not with a pasted token. Spacebrain's server doesn't support that sign-in yet. Until it does, use Muse, Claude Code, Cursor, or another client that accepts a header.

Approve or dismiss suggested changes

When the assistant suggests a change, it shows you a preview and asks whether to go ahead. You can also decide from Spacebrain:

1. Go to Settings → AI Agents.
2. On the token's row, select Open in Orbit. If changes are waiting, the button says Review 2 pending (with the current number).
3. In the token's Orbit thread, named Agent: followed by the token name, read the preview.
4. Select Confirm to make the change, or Dismiss to drop it.

Each proposal runs at most once. Approving in Orbit and approving in the assistant are the same thing, so whichever happens first counts. If the other one tries later, it's told the proposal is no longer waiting.

What you should see

• Answers come from the correct workspace.
• The token's row in Access tokens shows a recent Last used time.
• A suggested change appears in the token's Orbit thread. After you approve it, the change shows on the record.

Try your first change on a test record, then delete the test record.

Revoke access

1. Go to Settings → AI Agents.
2. On the token's row, select the trash icon (Revoke).
3. In Revoke access token?, select Revoke.

The token stops working on the assistant's next request. Proposals it already made stay in Orbit until you approve or dismiss them.

A token also stops working when it expires, when the person who created it leaves the workspace, or when the workspace moves to the Free plan.

If something goes wrong

When you contact support, include the token name and the time of the failed request. Never include the token itself.

FAQ

Can the assistant see everything in my workspace?

No. It sees only the packs the token allows, and only what the token creator could see, capped at Editor.

Who is responsible for an assistant's changes?

Changes run as the person who created the token. Review each proposal as you would a teammate's. Choose Read only when the assistant only needs to answer questions.

Does using an assistant cost credits?

Some actions that use credits in Orbit also show their credit cost on the proposal. AI features that spend credits inside Orbit, such as drafting inbox replies, aren't available to outside assistants yet.

Next step

Learn how approvals work in Orbit, your AI assistant.