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

# Connect your AI assistant

> Add the Kubit MCP server at https://agent.kubit.ai/mcp to Cursor, Codex, ChatGPT or another MCP client, then sign in with your Kubit account.

This page connects the Kubit MCP server to your AI assistant. At the end, you can ask your assistant a question about your Kubit data and get back a Kubit report. Setup takes about 5 minutes per client.

Every client uses the same server URL, `https://agent.kubit.ai/mcp`, and the same browser sign-in. Only the place you add the URL differs. The examples name the server `kubit-agent`, the name the Kubit plugin uses. Any name works.

## Before you start

* [ ] A Kubit account. Sign-up needs an early-access link from Kubit or an invite from your organization. See [Set up your organization](https://learn.kubit.ai/start-here/admin.md).
* [ ] One of the clients below, on a version that supports remote MCP servers over HTTP
* [ ] For the Kubit plugin: Node.js 18+, for `npx`

## Prompt for your coding agent

Paste this into Claude Code, Cursor or Codex to have it set up the connection:

```text theme={null}
Connect the Kubit MCP server to this coding agent. Follow https://learn.kubit.ai/ai-assistant/connect.md for the client you are running in.
Stop before the browser sign-in and tell me which command to run.
```

## Claude Code

Claude Code connects to Kubit in one of two ways. The Kubit plugin adds the MCP server and the [Kubit skills](https://learn.kubit.ai/ai-assistant/skills.md), and is the recommended setup. A manual setup adds the MCP server only.

### Install the Kubit plugin

#### 1. Run the installer

```bash theme={null}
npx @kubit-ai/agent-plugin
```

Pick **Claude Code** for the runtime, and **Global** (the default) or **Local** for the location. The plugin adds the Kubit MCP server as `kubit-agent`.

#### 2. Restart Claude Code

Restart Claude Code so it loads the server and the skills.

#### 3. Sign in

Run `/mcp`, pick `kubit-agent` and complete the sign-in in your browser.

#### 4. Pick a workspace

Run `/kubit-connect` to choose the organization and workspace for this conversation.

[Agent plugin](https://learn.kubit.ai/agent-observability/integrate/agent-plugin.md) covers the plugin's `/kubit-integrate` skill, which wires Kubit tracing into a repo.

### Add the MCP server manually

#### 1. Add the server

```bash theme={null}
claude mcp add --transport http kubit-agent https://agent.kubit.ai/mcp
```

The server is added for you, in the current project only. Add `--scope user` to use it in every project, or `--scope project` to write it to a shared `.mcp.json` at the project root.

#### 2. Sign in

In Claude Code, run `/mcp`, pick `kubit-agent` and choose **Authenticate**. Complete the sign-in in your browser.

To add the server by editing `.mcp.json` yourself, set `"type": "http"`. Without it, Claude Code doesn't load the server.

```json .mcp.json theme={null}
{
  "mcpServers": {
    "kubit-agent": {
      "type": "http",
      "url": "https://agent.kubit.ai/mcp"
    }
  }
}
```

## Cursor

Cursor connects through the Kubit plugin or a manual MCP config. The plugin also installs the [Kubit skills](https://learn.kubit.ai/ai-assistant/skills.md).

### Install the Kubit plugin

```bash theme={null}
npx @kubit-ai/agent-plugin --runtime cursor
```

Restart Cursor afterwards. Cursor asks you to sign in to the Kubit MCP server the first time a Kubit tool runs.

### Add the MCP server manually

#### 1. Open the MCP settings

In Cursor, open **Customize** and click **New MCP Server**.

#### 2. Add the config

```json mcp.json theme={null}
{
  "mcpServers": {
    "kubit-agent": {
      "url": "https://agent.kubit.ai/mcp"
    }
  }
}
```

#### 3. Sign in

Save the config, click **Connect** and complete the sign-in in your browser.

## Claude and Claude Desktop

Claude on the web and Claude Desktop connect through a custom connector.

#### 1. Add a custom connector

Open **Settings** > **Connectors** and click **Add custom connector**.

#### 2. Enter the URL

Name the connector `Kubit`, enter `https://agent.kubit.ai/mcp` as the **Remote MCP server URL** and click **Add**.

#### 3. Sign in

Click **Connect** and complete the sign-in in your browser.

Changing the connector's URL later clears its sign-in. Connect again after any URL change.

## Codex

Codex connects with its `codex mcp` commands or a `config.toml` entry.

#### 1. Add the server

```bash theme={null}
codex mcp add kubit-agent --url https://agent.kubit.ai/mcp
```

#### 2. Sign in

```bash theme={null}
codex mcp login kubit-agent
```

Complete the sign-in in your browser without pausing. The local callback that receives the sign-in expires after a short wait.

To configure the server by hand, add this block to `~/.codex/config.toml`, or to `.codex/config.toml` in a project to use it in that project only. A project file's settings override the global file.

```toml ~/.codex/config.toml theme={null}
[mcp_servers.kubit-agent]
url = "https://agent.kubit.ai/mcp"
auth = "oauth"
startup_timeout_sec = 30
tool_timeout_sec = 120
```

`tool_timeout_sec = 120` gives reports over wide date ranges time to finish. The Codex default is 60 seconds.

## ChatGPT, VS Code and other clients

Any MCP client that supports remote servers over streamable HTTP and OAuth sign-in can connect. Give it these settings:

| Setting | Value |
| - | - |
| **URL** | `https://agent.kubit.ai/mcp` |
| **Transport** | Streamable HTTP |
| **Authentication** | OAuth 2.1 authorization code with PKCE (`S256`). The client registers itself through dynamic client registration, so you don't enter a client ID or secret. |
| **Scopes** | `mcp:read mcp:write` |

**Availability:** Kubit accepts OAuth sign-in redirects from ChatGPT, Claude, Cursor, VS Code, Docker MCP Toolkit and clients that listen on `localhost` or `127.0.0.1`. A client that redirects anywhere else can't complete the sign-in.

## Kubit skills

The Kubit plugin installs 8 skills into Claude Code and Cursor, such as `/kubit-report` for reports and `/kubit-blame` for finding the commit behind a regression. Each one calls the Kubit MCP server. [Kubit skills](https://learn.kubit.ai/ai-assistant/skills.md) covers every skill, the installer flags and updates.

## Verify

Ask your assistant:

> "Which Kubit workspace am I connected to?"

The answer names your organization and workspace. The assistant gets them from the `init` tool. In Claude Code, `claude mcp list` also shows `kubit-agent` as connected. In Codex, `codex mcp list` does the same.

## If it fails

| Symptom | Cause | Fix |
| - | - | - |
| Every Kubit tool call returns an auth error | Sign-in not done, or the token is stale | Claude Code: run `/mcp`, pick `kubit-agent` and sign in. Codex: run `codex mcp login kubit-agent`. Claude: disconnect and connect the connector again. |
| Claude Code doesn't load a server from `.mcp.json` | The entry has a `url` but no `type` | Add `"type": "http"` to the entry |
| Kubit skills aren't listed after the plugin install | The client wasn't restarted | Restart Claude Code or Cursor, then run `/kubit-help` |
| The connector is listed in Claude but shows no tools | The connection didn't finish loading | Turn the connector off and on in **Settings** > **Connectors** |
| Cursor shows the server but its tools don't run | The server didn't reload after setup | In Cursor Settings (`Cmd/Ctrl + Shift + J`), open **Tools & MCPs** and turn `kubit-agent` off and on, or run **Developer: Reload Window** |
| Codex never lists the server | An older Codex build skips URL-based servers unless remote MCP support is turned on | Upgrade Codex (`npm install -g @openai/codex`). On older builds, add `rmcp_client = true` under `[features]` in `~/.codex/config.toml`. |
| The browser shows a connection error at the end of the Codex sign-in | The local callback expired | Run `codex mcp login kubit-agent` again and finish the sign-in without pausing |
| `Invalid session token. Call init to obtain a new one.` | The assistant sent a workspace token from an earlier session | Ask the assistant to start a new Kubit session, or run `/kubit-connect` |
| A report request times out | The date range is too wide for the client's tool timeout | Narrow the date range, or raise the client's tool timeout (`tool_timeout_sec` in Codex) |

## Next steps

* [MCP tools reference](https://learn.kubit.ai/ai-assistant/tools.md): what each Kubit tool does and its limits.
* [Prompt Kubit](https://learn.kubit.ai/ai-assistant/prompting.md): how to phrase questions so the MCP server builds the right report.


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