# Connect an AI assistant

> Copy your project's assistant address and add it to Claude.ai, Claude Desktop, ChatGPT, Claude Code or Cursor, with your account or an assistant key.

You can connect an AI assistant such as Claude or ChatGPT to a Spatibase project, so it can look through your content, find gaps and prepare draft entries for you. This page walks you through connecting each common assistant. It takes a few minutes and needs no programming. Building your own app with a coding agent instead? See [Build an app with your content and a coding agent](https://spatibase.com/docs/build/build-with-a-coding-agent/).

## How does an assistant connect to Spatibase?

Every Spatibase project has its own assistant address, which works with any assistant that supports MCP (Model Context Protocol), the standard way for AI assistants to use outside tools. You add that address to your assistant, then either sign in with your Spatibase account or give it a key.

| How it connects | Who can use it | Works with |
|---|---|---|
| **Sign in with your account** (no key) | Owners, editors and developers | Claude.ai, ChatGPT, Claude Desktop, Claude Code, and other clients that support MCP sign-in |
| **AI assistant key** | Owners create these keys | Claude Code, Claude Desktop, Cursor, your own agents |

Signing in is the simplest choice. The assistant can then do what your role allows, and you choose on a consent screen how much of that it may use. A key is useful for assistants that cannot sign in, or for a setup that should not depend on one person's account. See [What AI assistants can do](https://spatibase.com/docs/ai/what-assistants-can-do/) for the details of each option.

## Step 1: Copy your project's assistant address

The address is different for every project. Always copy it from the web app.

1. Open the project in Spatibase.
2. Select **AI agents** in the project menu and choose **Work on your content** (it is the one selected at first).
3. Open step 1, **Connect your assistant**, and use the copy button next to **This project's assistant address** (its tooltip says **Copy the address**).

The address looks like this, where `$PROJECT_ID` is the long id in your project's web address:

```http
https://mcp.spatibase.com/projects/$PROJECT_ID
```

Below the address, **Connect your assistant** has tabs with a ready-made setup for each assistant, with your address already filled in. What the tabs show depends on your role: owners see the tabs **Claude Code**, **Claude Desktop** and **Cursor** with a setup that uses a key, plus **Claude.ai or ChatGPT**, which signs in; editors and developers see **Claude.ai, ChatGPT or Claude Desktop** and **Claude Code**, both with sign-in. Each code box has a copy button.

## Using a key? Create one first (owners only)

You need a key only for the key-based setups in step 2. If you sign in with your account, skip this. Only project owners can create keys for AI assistants.

1. In the project's **API**, go to **Access & keys** and select **Create key** (**Create your first key** if there are no keys yet). On the **Members** page, **Add AI assistant** opens the same dialog.
2. Choose **For an AI assistant**, give the key a name, such as "Claude Code on my laptop", and optionally set when it expires.
3. Leave **Allow publishing** and **Allow deleting** off unless the assistant needs them.
4. Select **Create key**, copy the key from the **Copy your key now** dialog, tick the confirmation and select **Done**.

The key is shown only once. See [Access and API keys](https://spatibase.com/docs/publish/access-and-keys/) for replacing and revoking keys.

## Step 2: Add the address to your assistant

Follow the section for your assistant. In each case you add the address you copied in step 1.

### Claude.ai

1. In Claude.ai, open **Settings**, then **Connectors**, and select **Add custom connector**.
2. Give it a name such as "Spatibase" and paste the address.
3. Add the connector, then connect it. Claude opens a Spatibase window.
4. Sign in with your Spatibase account if you are not signed in yet.
5. On the **Connect an app to Spatibase** screen, choose what the assistant may do and select **Allow** (see [Step 3](https://spatibase.com/docs/ai/connect-an-assistant/#step-3-choose-what-the-assistant-may-do)).

On a Team or Enterprise plan, an organization owner may have to add the custom connector for the organization first.

### Claude Desktop

Claude Desktop uses the same connectors as Claude.ai.

1. Open **Settings**, then **Connectors**, and select **Add custom connector**.
2. Paste the address, then sign in with your Spatibase account and select **Allow** on the consent screen.

Owners who prefer a key can add Spatibase to Claude Desktop's configuration file instead: in Claude Desktop, open **Settings**, then **Developer**, and select **Edit Config** to open `claude_desktop_config.json`. This uses the small `mcp-remote` bridge, which needs Node.js on your computer:

```json
{
  "mcpServers": {
    "spatibase": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.spatibase.com/projects/$PROJECT_ID",
               "--header", "Authorization: Bearer ${SPATIBASE_KEY}"],
      "env": { "SPATIBASE_KEY": "YOUR_EDIT_KEY" }
    }
  }
}
```

Replace the address with your own (or copy the snippet from the **Claude Desktop** tab, which already contains it) and `YOUR_EDIT_KEY` with an AI assistant key, save the file and restart Claude Desktop.

### ChatGPT

1. In ChatGPT, open **Settings** and add a custom connector with the address. Depending on your ChatGPT plan, custom connectors may first have to be turned on in the settings, or by an administrator of your workspace.
2. Sign in with your Spatibase account when ChatGPT asks.
3. On the consent screen, choose what the assistant may do and select **Allow**.

### Claude Code

Run one command in a terminal. Copy it from the **Claude Code** tab under **Connect your assistant** on the **AI agents** page, which already contains your address. Owners see the command with a key there (leave out the `--header` part to sign in instead); editors and developers see the sign-in command.

**Sign in with your account** (any role):

```bash
claude mcp add --transport http spatibase https://mcp.spatibase.com/projects/$PROJECT_ID
```

Then start Claude Code, run `/mcp`, choose **spatibase** and sign in with your Spatibase account in the browser.

**With an AI assistant key** (owners):

```bash
claude mcp add --transport http spatibase https://mcp.spatibase.com/projects/$PROJECT_ID \
  --header "Authorization: Bearer YOUR_EDIT_KEY"
```

Replace `YOUR_EDIT_KEY` with an AI assistant key.

### Cursor

Owners can connect Cursor with an AI assistant key. Add this to Cursor's MCP settings file (`.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for all projects), then restart Cursor:

```json
{
  "mcpServers": {
    "spatibase": {
      "url": "https://mcp.spatibase.com/projects/$PROJECT_ID",
      "headers": { "Authorization": "Bearer YOUR_EDIT_KEY" }
    }
  }
}
```

Replace the address with your own (or copy the snippet from the **Cursor** tab) and `YOUR_EDIT_KEY` with an AI assistant key.

### Other MCP clients

Any assistant or agent that supports remote MCP servers over HTTP (the "Streamable HTTP" transport) can connect:

- If it supports MCP sign-in (OAuth), add the address without a key and sign in when it asks.
- Otherwise, send an AI assistant key in the `Authorization: Bearer` header of every request.

Developers building their own agent will find the technical details in [MCP server](https://spatibase.com/docs/ai/mcp-server/) and [OAuth for MCP clients](https://spatibase.com/docs/ai/oauth/).

## Step 3: Choose what the assistant may do

When you sign in, Spatibase shows a consent screen, **Connect an app to Spatibase**, with the app's name, the project, and **What may it do?**:

| Option | What it allows | Selected at first |
|---|---|---|
| **Read the project** | See published entries, groups and how the content is organised. | Always included |
| **Edit drafts** | Create and change drafts. Nothing goes live until someone marks it ready and publishes the project. | Yes |
| **Publish** | Put changes live without a person checking them. | No |
| **Delete** | Delete entries and files (they go to the trash for 30 days). | No |
| **Change the content model** | Change the content model and project settings. | No |

Your role sets the limit: owners can tick all five, editors all but **Change the content model**, developers only **Read the project**. Options your role does not allow are greyed out with a note, and the screen only lists what the app asked for. Tick only what the job needs, then select **Allow** (or **Cancel** to refuse). To change your choice later, connect the app again: the new choice replaces the old one.

> **Tip:** If the screen warns that the app runs on your own computer, only allow it if you started connecting it yourself just now.

## Step 4: Check that it works

Ask your assistant a first question, such as "Summarize this Spatibase project: what types it has, how many entries there are, and anything that looks incomplete."

If it answers with your project's types and numbers, you are connected. For more ideas, see [Things to ask](https://spatibase.com/docs/ai/what-assistants-can-do/#things-to-ask).

## How do I disconnect an assistant?

- **Signed-in assistants:** open the account menu, select **Connected apps** and select **Disconnect** next to the app. It loses access straight away. Owners and Developers can also disconnect anyone's signed-in assistant from the project's **Members** page (**AI assistants**, **Disconnect**).
- **Key-based assistants:** an owner or developer revokes the key in the project's **API**, on **Access & keys**. The assistant stops working at once.

## What if it does not connect?

- **The assistant only reads, and does not see drafts.** On a public project, an assistant can connect without signing in and can then only read published content. Use the sign-in or connect option in the assistant's connector settings to sign in.
- **It asks for a key, but you are an editor or developer.** You do not need one: sign in with your account instead. Only owners create keys.
- **"401" or "invalid key".** The key is wrong, revoked, expired or from another project. Use a key from this project together with this project's address.

More fixes are in [What AI assistants can do](https://spatibase.com/docs/ai/what-assistants-can-do/#if-something-does-not-work).

## Related

- [What AI assistants can do](https://spatibase.com/docs/ai/what-assistants-can-do/)
- [Access and API keys](https://spatibase.com/docs/publish/access-and-keys/)
- [MCP server reference](https://spatibase.com/docs/ai/mcp-server/)
- [OAuth for MCP clients](https://spatibase.com/docs/ai/oauth/)
- [Build an app with your content and a coding agent](https://spatibase.com/docs/build/build-with-a-coding-agent/)