# Connect a client

Add the remote MCP server at `https://mcp.tomba.io/mcp` to your AI client. Clients that support MCP authorization sign you in to Tomba with OAuth; the others send your API key and secret in headers.

| Client                            | Where the setting lives                              | Authentication           |
| --------------------------------- | ---------------------------------------------------- | ------------------------ |
| [Claude Desktop](#claude-desktop) | Customize → Connectors, in your Claude account       | OAuth                    |
| [Claude Code](#claude-code)       | `claude mcp add`                                     | OAuth or API key headers |
| [ChatGPT](#chatgpt)               | A developer mode app                                 | OAuth                    |
| [VS Code](#vs-code)               | `.vscode/mcp.json`, or the user configuration        | OAuth or API key headers |
| [Cursor](#cursor)                 | `~/.cursor/mcp.json` or `.cursor/mcp.json`           | API key headers          |
| [Windsurf](#windsurf)             | `mcp_config.json`                                    | API key headers or OAuth |
| [Zed](#zed)                       | `settings.json`                                      | OAuth or bearer token    |
| [Gemini CLI](#gemini-cli)         | `~/.gemini/settings.json` or `.gemini/settings.json` | OAuth or API key headers |
| [Cline](#cline)                   | `cline_mcp_settings.json`                            | API key headers          |

`~` is your home directory: `/Users/<name>` on macOS, `/home/<name>` on Linux, and `C:\Users\<name>` on Windows. For header authentication, copy your key and secret as described in [Get your key and secret](/authentication#get-your-key-and-secret). The [Authentication](/llm/remote-mcp/introduction#authentication) section of the server page describes each method.

After you connect, check the setup:

1. The client shows the Tomba server as connected. Where the client lists tools, it shows 38; each section below says where to look.
2. Ask the assistant to run the `list_flags` tool. A list of flags, even an empty one, means your credentials work. An authentication error means they don't: see [Troubleshooting](#troubleshooting).

## Claude Desktop

Claude Desktop adds remote servers as custom connectors, which live in your Claude account rather than in a local file. Connectors authenticate with OAuth and can't send API key headers; to use an API key with Claude Desktop, run the [local MCP server](/llm/local-mcp/introduction#claude-desktop) instead.

1. In Claude, open **Customize → Connectors**, select **+**, then **Add custom connector**.
2. Enter the URL `https://mcp.tomba.io/mcp`. Leave the OAuth fields under **Advanced settings** empty.
3. Select **Add**, then **Connect**. Sign in to Tomba in the browser window that opens, and approve access.

On a Team or Enterprise plan, an Owner adds the connector under **Organization settings → Connectors** (**Add**, then **Custom**, then **Web**). Each member then selects **Connect** on it under **Customize → Connectors**.

To verify, open the Tomba connector under **Customize → Connectors** and check its tool list. To use the tools in a conversation, turn the connector on from the **+** menu under **Connectors**.

## Claude Code

Add the server, then sign in:

```bash
claude mcp add --transport http --scope user tomba https://mcp.tomba.io/mcp
claude mcp login tomba
```

`claude mcp login` opens a browser window where you sign in to Tomba. You can also run `/mcp` in a session, select `tomba`, and authenticate from there.

To send your key and secret instead of signing in:

```bash
claude mcp add --transport http --scope user tomba https://mcp.tomba.io/mcp \
  --header "X-Tomba-Key: $TOMBA_API_KEY" \
  --header "X-Tomba-Secret: $TOMBA_SECRET_KEY"
```

The shell expands the variables when you run the command, so the configuration stores the values. `--scope user` saves the server in `~/.claude.json` for all your projects. The default scope, `local`, applies to the current project only, and `--scope project` writes a `.mcp.json` file meant to be committed, so don't use it with your secret.

To verify, run `claude mcp list`: `tomba` shows as connected. In a session, `/mcp` shows the server with 38 tools.

## ChatGPT

ChatGPT connects to remote MCP servers through developer mode, which is available on the web for Plus, Pro, Business, Enterprise, and Education accounts. It authenticates with OAuth and can't send API key headers.

1. Open **Settings → Security and login** and turn on **Developer mode**.
2. Open **ChatGPT Plugins**, select **+**, and create an app for the remote MCP server `https://mcp.tomba.io/mcp` with OAuth authentication. Sign in to Tomba and approve access.
3. In a conversation, choose **Developer mode** from the **+** menu and select the Tomba app.

ChatGPT asks you to confirm write actions before it runs them. Among the Tomba tools, only `create_flag` and `create_lead` change data.

To verify, open the app's details page from settings: it lists the tools. Use **Refresh** there to load changes after the server is updated.

## VS Code

Put the server in `.vscode/mcp.json` for one workspace, or run **MCP: Open User Configuration** from the Command Palette to add it for all workspaces:

```json
{
    "servers": {
        "tomba": {
            "type": "http",
            "url": "https://mcp.tomba.io/mcp"
        }
    }
}
```

When VS Code first connects, it opens a browser window where you sign in to Tomba.

To send your key and secret instead, declare them as inputs. VS Code asks for both values on first use and stores them securely:

```json
{
    "inputs": [
        {
            "type": "promptString",
            "id": "tomba-key",
            "description": "Tomba API key",
            "password": true
        },
        {
            "type": "promptString",
            "id": "tomba-secret",
            "description": "Tomba secret",
            "password": true
        }
    ],
    "servers": {
        "tomba": {
            "type": "http",
            "url": "https://mcp.tomba.io/mcp",
            "headers": {
                "X-Tomba-Key": "${input:tomba-key}",
                "X-Tomba-Secret": "${input:tomba-secret}"
            }
        }
    }
}
```

To verify, run **MCP: List Servers**: `tomba` is running. In the Chat view, **Configure Tools** lists the 38 Tomba tools.

## Cursor

Add the server to `~/.cursor/mcp.json` for all projects, or to `.cursor/mcp.json` in a project:

```json
{
    "mcpServers": {
        "tomba": {
            "url": "https://mcp.tomba.io/mcp",
            "headers": {
                "X-Tomba-Key": "${env:TOMBA_API_KEY}",
                "X-Tomba-Secret": "${env:TOMBA_SECRET_KEY}"
            }
        }
    }
}
```

Cursor replaces each `${env:…}` reference with an environment variable of the Cursor process. Set `TOMBA_API_KEY` and `TOMBA_SECRET_KEY` where Cursor inherits them, for example by starting Cursor from a terminal that has them, or write the values in the file.

To verify, open **Customize** in the Cursor sidebar: `tomba` is listed and enabled, with its tools.

## Windsurf

Windsurf is now called Devin Desktop. In the Cascade panel, open the **…** menu and select **Open MCP config file** in the MCPs section, then add:

```json
{
    "mcpServers": {
        "tomba": {
            "serverUrl": "https://mcp.tomba.io/mcp",
            "headers": {
                "X-Tomba-Key": "${env:TOMBA_API_KEY}",
                "X-Tomba-Secret": "${env:TOMBA_SECRET_KEY}"
            }
        }
    }
}
```

`${env:…}` reads an environment variable. To sign in with OAuth instead, leave out `headers`.

This file configures the Cascade agent. The Devin Local agent, the default for new tabs, reads MCP servers from the Devin CLI configuration instead; see [Devin's MCP documentation](https://docs.devin.ai/desktop/cascade/mcp).

To verify, open the MCPs section of the **…** menu: it lists `tomba` with the number of tools it provides, 38.

## Zed

Run **zed: open settings file** from the command palette and add the server under `context_servers`:

```json
{
    "context_servers": {
        "tomba": {
            "url": "https://mcp.tomba.io/mcp"
        }
    }
}
```

With no `Authorization` header configured, Zed signs you in with OAuth. To use your API key instead, add `"headers": { "Authorization": "Bearer <token>" }`, with the token built as described in [API key as a bearer token](/llm/remote-mcp/introduction#api-key-as-a-bearer-token).

To verify, open **Settings → AI → MCP Servers**: the dot next to `tomba` is green, and its tooltip says "Server is active".

## Gemini CLI

Add the server for your user, then sign in from a Gemini CLI session:

```bash
gemini mcp add --transport http --scope user tomba https://mcp.tomba.io/mcp
```

In Gemini CLI, run `/mcp auth tomba` and sign in to Tomba in the browser window that opens.

To send your key and secret instead:

```bash
gemini mcp add --transport http -H "X-Tomba-Key: $TOMBA_API_KEY" -H "X-Tomba-Secret: $TOMBA_SECRET_KEY" --scope user tomba https://mcp.tomba.io/mcp
```

With `--scope user`, the server is saved in `~/.gemini/settings.json`; the default scope, `project`, uses `.gemini/settings.json` in the current directory. If you edit the file directly, write the entry the way `gemini mcp add` does, with `"type": "http"`. Older versions of Gemini CLI use `httpUrl` instead of `url` and `type`.

```json
{
    "mcpServers": {
        "tomba": {
            "url": "https://mcp.tomba.io/mcp",
            "type": "http"
        }
    }
}
```

To verify, run `gemini mcp list`: `tomba` shows as connected. In a session, `/mcp list` shows the server's tools.

## Cline

1. In the Cline panel, select the **MCP Servers** icon, then the **Remote Servers** tab.
2. Enter the server name `tomba` and the URL `https://mcp.tomba.io/mcp`, choose **Streamable HTTP**, and select **Add Server**.
3. Select **Configure MCP Servers** to open `cline_mcp_settings.json`, and add your key and secret as headers:

```json
{
    "mcpServers": {
        "tomba": {
            "type": "streamableHttp",
            "url": "https://mcp.tomba.io/mcp",
            "headers": {
                "X-Tomba-Key": "ta_xxxx",
                "X-Tomba-Secret": "ts_xxxx"
            }
        }
    }
}
```

Replace `ta_xxxx` and `ts_xxxx` with your key and secret. To verify, check that the Tomba tools appear under the server in the **MCP Servers** panel.

## Other clients

In any client that supports remote MCP servers, add a server with the Streamable HTTP transport (some clients call it HTTP) and the URL `https://mcp.tomba.io/mcp`. If the client supports MCP authorization, leave authentication empty and sign in when asked. Otherwise, send the `X-Tomba-Key` and `X-Tomba-Secret` headers, or `Authorization: Bearer` with the [encoded key and secret](/llm/remote-mcp/introduction#api-key-as-a-bearer-token).

## Troubleshooting

| Symptom                                                               | What to do                                                                                                                                                                                                      |
| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The client says the server needs authentication.                      | Finish the sign-in: `claude mcp login tomba` in Claude Code, `/mcp auth tomba` in Gemini CLI, or **Connect** on the Claude connector. With headers, check that both `X-Tomba-Key` and `X-Tomba-Secret` are set. |
| The tools are listed, but every call returns an authentication error. | The server only checks credentials when a tool calls the API. Check the key and secret, and whether the key has expired: see [Key expiry](/authentication#key-expiry).                                          |
| `usage_info` and `get_logs` fail while other tools work.              | You signed in with OAuth, which these two tools don't accept. Connect with your key and secret to use them.                                                                                                     |
| Tool calls fail with a rate limit error.                              | Your plan's limit was reached; the server already retried twice. See [Handle 429 responses](/rate-limits#handle-429-responses).                                                                                 |
| You want to remove a client's access.                                 | For OAuth, revoke the app under [Connected apps](https://app.tomba.io/settings/connected-apps). For headers, [rotate the key](/authentication#rotate-keys).                                                     |