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

# Connect an AI app

> Step-by-step setup for Claude, ChatGPT, Gemini, Claude Code and Codex.

Each AI app has its own place to add an MCP server, but the Spacebase side is the same every time: enter the connector address, sign in to Spacebase, and approve read-only access.

## Before you start

The connector address for every app is:

```text theme={null}
https://spacebaseapp.com/mcp
```

> [!NOTE]
>
> You need the Enterprise plan, the Spacebase AI module and the **Access AI functionality** permission. See [Who can connect](https://docs.spacebaseapp.com/ai/connectors.md#who-can-connect).

Have your Spacebase login ready. During setup the app opens a Spacebase sign-in window (password, Google, or your company's single sign-on), then a consent screen titled **Authorize** that lists one permission: *Read your Spacebase lease portfolio through AI assistants (read-only)*. Click **Authorize** to finish.

> [!TIP]
>
> The consent screen names the app that made the request and where it will return you. Only authorize a request you started yourself.

## Claude

Custom connectors are available in Claude on the web, Claude Desktop and Cowork. Claude.ai and Claude Desktop share one connection, so you only need to connect once.

**1. Open Connectors**

Go to **Customize** and then **Connectors**. In Claude Desktop this is under **Settings** → **Connectors**.

**2. Add a custom connector**

Click **+ Add** and choose **Add custom connector**. Enter *Spacebase* as the name and `https://spacebaseapp.com/mcp` as the remote MCP server URL, then continue.

**3. Choose how to sign in**

Leave the authentication settings at their defaults, pick **Sign in now**, and click **Add**. A Spacebase sign-in window opens. Sign in and click **Authorize**.

**4. Turn it on in a chat**

In a conversation, click the **+** button at the lower left, choose **Connectors**, and make sure **Spacebase** is switched on. Then ask a question about your portfolio.

**Team and Enterprise plans.** An Owner or Primary Owner adds the connector once under **Organization settings** → **Connectors** using the same steps. Each member then opens **Customize** → **Connectors**, finds Spacebase and clicks **Connect** to sign in with their own Spacebase account.

**Remove.** Open **Customize** → **Connectors**, find Spacebase and choose **Remove** from its menu. Then disconnect it in Spacebase as described in [Disconnect an assistant](https://docs.spacebaseapp.com/ai/connectors.md#disconnect-an-assistant).

## ChatGPT

ChatGPT manages custom MCP servers on its **Plugins** page. Custom MCP servers are available on the Plus, Pro, Business, Enterprise and Edu plans. On Business, Enterprise and Edu workspaces an administrator first grants the **Create custom MCP servers** permission under **Workspace settings** → **Permissions & roles**.

**1. Open Plugins**

From ChatGPT's main page, click the **Plugins** button in the left sidebar. You can also go straight to [chatgpt.com/plugins](https://chatgpt.com/plugins).

**2. Create the connector**

Click **Add** button and choose **Add custom MCP server**. Enter *Spacebase* as the name and a short description, enter `https://spacebaseapp.com/mcp` as the MCP server URL, and leave authentication set to **OAuth**.

**3. Confirm and create**

Read the warning about third-party servers and click **I understand and want to continue**, then **Create as a plugin**. ChatGPT scans the server and lists the Spacebase tools.

**4. Sign in to Spacebase**

ChatGPT opens the Spacebase sign-in window. Sign in and click **Authorize**.

**5. Use it in a conversation**

In a new chat, type **@** in the message box, choose **Spacebase**, and ask your question.

**Business, Enterprise and Edu workspaces.** If ChatGPT says you need workspace admin permission to create a draft app, ask an administrator to grant you **Create custom MCP servers**. An administrator can also create the connector once and publish it to the whole workspace from the **Plugins** section of the Admin console. Each member still signs in with their own Spacebase account.

**Remove.** Open **Settings** → **Plugins**, open the Spacebase plugin and uninstall it. Then disconnect it in Spacebase as described in [Disconnect an assistant](https://docs.spacebaseapp.com/ai/connectors.md#disconnect-an-assistant).

## Gemini

### Gemini web app

Custom apps are managed under **Connected Apps** in the Gemini web app at [gemini.google.com](https://gemini.google.com).

**1. Open Connected Apps**

Click **Settings** at the bottom of the left panel, then **Connected Apps**. If you don't see it, open **Personal Intelligence** first, then **Connected Apps**.

**2. Add a custom app**

Under **Custom apps**, click **Add a custom app**, enter `https://spacebaseapp.com/mcp` as the MCP server URL, and click **Next**.

**3. Sign in to Spacebase**

Follow the on-screen prompts. When the Spacebase sign-in window opens, sign in and click **Authorize**.

**4. Use it in a chat**

Type **@** in the message box and choose **Spacebase** so Gemini uses the connector for that question.

To pause the connector, toggle it off under **Custom apps**. To remove it, open **More details** on the Spacebase app and choose **Remove app**, then disconnect it in Spacebase as described in [Disconnect an assistant](https://docs.spacebaseapp.com/ai/connectors.md#disconnect-an-assistant).

**Gemini Enterprise.** A team administrator adds the connector for the whole team: in Gemini Enterprise, open **Settings & help**, choose the team, go to **Manage team** → **Connected apps**, and click **Add MCP Server** with the same address. Each member signs in to Spacebase with their own account the first time they use it.

### Gemini CLI

Add Spacebase to the `mcpServers` section of `~/.gemini/settings.json`. Leave the OAuth details out: Gemini CLI discovers them from the server.

```json theme={null}
{
  "mcpServers": {
    "spacebase": {
      "httpUrl": "https://spacebaseapp.com/mcp",
      "oauth": {
        "enabled": true
      }
    }
  }
}
```

Start Gemini CLI and run `/mcp auth spacebase`. A browser window opens for the Spacebase sign-in and consent screen. Tokens are stored in `~/.gemini/mcp-oauth-tokens.json`.

Use `gemini mcp list` to check the connection and `gemini mcp remove spacebase` to remove it.

## Claude Code

Add the server from the terminal, then sign in from inside Claude Code.

```bash theme={null}
claude mcp add --transport http spacebase https://spacebaseapp.com/mcp
```

By default the server is available in the current project only. Add `--scope user` to make it available in every project:

```bash theme={null}
claude mcp add --transport http --scope user spacebase https://spacebaseapp.com/mcp
```

Start Claude Code and run `/mcp`. Select **spacebase** and follow the browser sign-in. You can also sign in without opening Claude Code:

```bash theme={null}
claude mcp login spacebase
```

Claude Code can fetch complete results into its workspace and analyze them with code, so it's a good fit for questions that span hundreds of expense records or dates. See [Downloading results as CSV](https://docs.spacebaseapp.com/ai/connectors/tools.md#downloading-results-as-csv).

**Share with your team.** To make the connector part of a repository, add it to `.mcp.json` at the project root. Each person still signs in with their own Spacebase account.

```json theme={null}
{
  "mcpServers": {
    "spacebase": {
      "type": "http",
      "url": "https://spacebaseapp.com/mcp"
    }
  }
}
```

**Remove.** Run `claude mcp logout spacebase` to clear the sign-in and `claude mcp remove spacebase` to delete the server. Then disconnect it in Spacebase as described in [Disconnect an assistant](https://docs.spacebaseapp.com/ai/connectors.md#disconnect-an-assistant). Each Claude Code installation appears as its own row there.

## Codex

### Codex CLI

Register the server and sign in:

```bash theme={null}
codex mcp add spacebase --url https://spacebaseapp.com/mcp
codex mcp login spacebase
```

The second command opens a browser window for the Spacebase sign-in and consent screen. Tokens refresh automatically afterwards.

If you prefer editing configuration directly, add this to `~/.codex/config.toml` and run `codex mcp login spacebase`:

```toml theme={null}
[mcp_servers.spacebase]
url = "https://spacebaseapp.com/mcp"
```

Use `codex mcp list` to check the connection, `codex mcp logout spacebase` to clear the sign-in, and remove the `[mcp_servers.spacebase]` section to delete the server.

### Codex IDE extension and desktop app

**1. Open MCP servers**

Open the Codex settings and select **MCP servers**.

**2. Add the server**

Choose **Add server**, select **Streamable HTTP**, enter *spacebase* as the name and `https://spacebaseapp.com/mcp` as the URL.

**3. Authenticate**

Select **Authenticate** when prompted and complete the Spacebase sign-in. Restart the extension or app if asked.

After removing the server in Codex, disconnect it in Spacebase as described in [Disconnect an assistant](https://docs.spacebaseapp.com/ai/connectors.md#disconnect-an-assistant).

## Troubleshooting

> [accordion] The app says I'm not authorized, or the connection fails right after I sign in
>
> Your account is failing one of the access checks. Confirm with your administrator that your company is on the Enterprise plan with the Spacebase AI module enabled, and that your user has the **Access AI functionality** permission. If you connected before and lost access later, the **AI Connectors** page in Spacebase shows a banner explaining that the connected apps can no longer read your data.

> [accordion] The sign-in window opened but the app never finished connecting
>
> Try again and complete the sign-in in the same browser the app opened. The **Authorize** screen appears right after you sign in. If your company uses single sign-on and you land on the Spacebase dashboard instead of the consent screen, start the connection again from the app.

> [accordion] ChatGPT says I need workspace admin permission to create a draft app
>
> Your ChatGPT account belongs to a Business, Enterprise or Edu workspace where custom MCP servers are restricted. Ask an administrator to grant you **Create custom MCP servers** under **Workspace settings** → **Permissions & roles**, or to create and publish the Spacebase connector for the workspace.

> [accordion] The app asks me to reconnect after it worked before
>
> Either the connection was disconnected from the **AI Connectors** page in Spacebase, or its 90-day renewal token expired. Sign in again from the app. If you no longer want the connection, remove it in the app as well.

> [accordion] I see an 'Unsupported protocol version' error
>
> Spacebase serves the MCP 2026-07-28 revision only. The app you're using is on an older version of MCP. Update the app and connect again. For Claude Code, run `claude update`.

> [accordion] I see a 'Rate limit exceeded' error
>
> The connector allows 30 tool calls a minute and 300 an hour per user. Wait a minute and ask again. Long analyses go faster when the assistant uses the summary totals or a CSV download instead of paging through every row. See [Limits](https://docs.spacebaseapp.com/ai/connectors/tools.md#limits).

> [accordion] I switched companies in Spacebase and the assistant's answers changed
>
> The connector follows the company you're currently signed in to. If you belong to more than one company, switch back in Spacebase and ask again.

> [accordion] A download link the assistant gave me doesn't work
>
> See [Downloading results as CSV](https://docs.spacebaseapp.com/ai/connectors/tools.md#downloading-results-as-csv) for what each message means. Most often the link has expired after 24 hours, or you're signed in to Spacebase as a different user or company than when the link was created.

If none of these help, email [support@spacebaseapp.com](mailto:support@spacebaseapp.com) with the app you're using and the time of the failed attempt.


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