Connect your AI assistant

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.
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:

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, and is the recommended setup. A manual setup adds the MCP server only.

Install the Kubit plugin

Run the installer

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.

Restart Claude Code

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

Pick a workspace

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

Agent plugin covers the plugin’s /kubit-integrate skill, which wires Kubit tracing into a repo.

Add the MCP server manually

Add the server

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.

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

.mcp.json

{
  "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.

Install the Kubit plugin

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

Open the MCP settings

In Cursor, open Customize and click New MCP Server.

Add the config

mcp.json

{
  "mcpServers": {
    "kubit-agent": {
      "url": "https://agent.kubit.ai/mcp"
    }
  }
}

Claude and Claude Desktop

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

Add a custom connector

Open Settings > Connectors and click Add custom connector.

Enter the URL

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

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.

Add the server

codex mcp add kubit-agent --url https://agent.kubit.ai/mcp

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.

~/.codex/config.toml

[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 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: what each Kubit tool does and its limits.
Prompt Kubit: how to phrase questions so the MCP server builds the right report.

Start here

Agent Observability

Product Analytics

Kubit in your AI assistant

Bring your own warehouse

Connect your AI assistant

Before you start

Prompt for your coding agent

Claude Code

Install the Kubit plugin

Run the installer

Restart Claude Code

Pick a workspace

Add the MCP server manually

Add the server

Cursor

Install the Kubit plugin

Add the MCP server manually

Open the MCP settings

Add the config

Claude and Claude Desktop

Add a custom connector

Enter the URL

Codex

Add the server

ChatGPT, VS Code and other clients

Kubit skills

Verify

If it fails

Next steps

​Before you start

​Prompt for your coding agent

​Claude Code

​Install the Kubit plugin

Run the installer

Restart Claude Code

Sign in

Pick a workspace

​Add the MCP server manually

Add the server

Sign in

​Cursor

​Install the Kubit plugin

​Add the MCP server manually

Open the MCP settings

Add the config

Sign in

​Claude and Claude Desktop

Add a custom connector

Enter the URL

Sign in

​Codex

Add the server

Sign in

​ChatGPT, VS Code and other clients

​Kubit skills

​Verify

​If it fails

​Next steps

Before you start

Prompt for your coding agent

Claude Code

Install the Kubit plugin

Add the MCP server manually

Cursor

Install the Kubit plugin

Add the MCP server manually

Claude and Claude Desktop

Codex

ChatGPT, VS Code and other clients

Kubit skills

Verify

If it fails

Next steps