# Connect an AI client with MCP

> Kaitoi is an MCP server. Add it to Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code and other MCP clients, and your agent can search nodes, run graphs and bring results back from your Kaitoi account.

Source: https://kaitoi.io/docs/core/mcp/
Section: Kaitoi Core
Written for: Anyone who wants to drive Kaitoi from an AI assistant, a coding agent or an editor.
Prerequisites: A Kaitoi Studio account with MCP access, included from the Indie plan up; An MCP client that can connect to remote servers
Last reviewed: 2026-10-05

---

Kaitoi Studio is a Model Context Protocol (MCP) server. Connect it to the AI
client you already use and that client can search the node catalogue, run a
node or a whole graph, build and save projects, upload files and fetch the
results. It works in your own Kaitoi account, with your projects, files and
credits.

The agent builds graphs in its own working copy. Ask it to save the work as a
project and the project opens in Kaitoi like any other. To change an existing
project, ask the agent to load it first. A quick single-node run returns its
result but does not create a project.

Every client uses one server URL:

```text
https://mcp.studio.kaitoi.io
```

It is also shown in Kaitoi under **Settings → MCP → MCP Access**, with a copy
button.

## Before you start

MCP access is included in the Indie plan and above. If your account does not
have it, the MCP settings page says it is available in Indie, and the server
refuses the connection.

There are two ways for a client to sign in:

- **OAuth**, the recommended way. You add the server URL to your client, the
  client opens a Kaitoi sign-in page in your browser, and you approve it. You
  never paste a secret into a config file, and the client renews access on its
  own, although it may ask you to sign in again from time to time. Use it for
  every client on this page except Gemini CLI, which is set up with a static
  token.
- **A static token**, for scripts, CI and clients that cannot complete a browser
  sign-in. See [Static tokens](#static-tokens).

When a client signs in with OAuth you see an **Authorize access** page that
names the client and shows the permissions it asked for. There are two:

| Permission | Allows |
|---|---|
| Read your projects, graphs, nodes, and files | Required. Lets the agent look at your account and the node catalogue. |
| Create and modify projects, graphs, nodes, files, and runs | Optional. Lets the agent build graphs, upload files and start runs. Untick it for an agent that can look but not change or run anything. |

If you are not signed in to Kaitoi in that browser, you are asked to sign in
first and then brought back to the same page. Once you click **Authorize**, the
client appears under **Settings → MCP → MCP Access → Connected Apps**.

Kaitoi can also write the setup for you. Open **Settings → MCP → MCP Access →
MCP Setup**, pick your client, and copy the command or configuration it
generates. It covers Claude, Claude Code, Cursor, VS Code, Gemini CLI and
Windsurf. For Gemini CLI, use the command in the [Gemini CLI](#gemini-cli)
section instead, which keeps the token out of your project folder. For
ChatGPT, Codex and Zed, follow this page.

## Claude

This covers Claude on the web, Claude Desktop and the Claude mobile apps. Claude
connects to Kaitoi from Anthropic's servers, so a connector you add once works
in all of them.

1. In Claude, open **Customize → Connectors**.
2. Click **+**, then **Add custom connector**.
3. Name it `Kaitoi` and paste the server URL. If Claude shows more settings,
   keep the suggested sign-in options. Click **Add**.
4. Click **Connect**, then approve the Kaitoi sign-in in the browser.

On the Free plan Claude allows one custom connector. On Team and Enterprise
plans an organization owner adds the connector under **Organization settings →
Connectors**, and members then find it under **Customize → Connectors** and
click **Connect**.

Use OAuth with Claude. Some organizations have Claude's request header option,
which is in beta. There, a static token also works: choose no sign-in and add an
`Authorization` header with the value `Bearer <token>`. Everyone who uses that
connector then shares the token's access.

## ChatGPT

ChatGPT connects to custom MCP servers on the web, not in the mobile apps.
Which ChatGPT plans can add one, and whether a workspace admin has to allow it
first, is set by OpenAI. Check OpenAI's article on
[developer mode and MCP apps](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt)
for the current rules.

OpenAI is partway through renaming apps to plugins, so the labels you see may
differ from these:

1. In ChatGPT on the web, open **Plugins**, click the **+** button, and choose
   **Create custom MCP server**.
2. Name it `Kaitoi`, add a short description such as "Build and run Kaitoi
   graphs", and enter the server URL under **Connection**.
3. Set **Authentication** to **OAuth**, accept the warning, and click **Create
   as a plugin**. Approve the Kaitoi sign-in when it opens.
4. Review the tools ChatGPT found and install the plugin.
5. Start a new chat, type `@` and pick Kaitoi.

If your account still shows the older apps layout, follow OpenAI's article
linked above instead: it turns on **Developer mode** under **Settings → Apps →
Advanced settings** and creates the app from there.

ChatGPT does not accept a static token. Use OAuth.

## Claude Code

Add the server from a terminal:

```bash
claude mcp add --transport http --scope user kaitoi https://mcp.studio.kaitoi.io
```

`--scope user` makes Kaitoi available in every project. Leave it out to add it
to the current project only.

Then start Claude Code, run `/mcp`, select `kaitoi` and follow the browser
sign-in.

## Codex

The Codex CLI, the Codex IDE extension and the Codex app share one
configuration on the same computer, so adding Kaitoi in one adds it in all
three. From a terminal:

```bash
codex mcp add kaitoi --url https://mcp.studio.kaitoi.io
```

Codex opens the Kaitoi sign-in in your browser straight away. If you close it,
or need to sign in again later, run:

```bash
codex mcp login kaitoi
```

You can do the same without a terminal. In the Codex app, open **Settings → MCP
servers**. In the IDE extension, open its gear menu and choose **MCP servers**.
Then click **Add server**, name it `kaitoi`, choose **Streamable HTTP**, paste
the server URL and save. Restart the app, or choose **Restart extension** in the
IDE, then click **Authenticate**.

The configuration lands in `~/.codex/config.toml`:

```toml
[mcp_servers.kaitoi]
url = "https://mcp.studio.kaitoi.io"
```

## Cursor

Add Kaitoi to `~/.cursor/mcp.json` to use it in every project, or to
`.cursor/mcp.json` inside one project:

```json
{
  "mcpServers": {
    "kaitoi": {
      "url": "https://mcp.studio.kaitoi.io"
    }
  }
}
```

Save the file. Cursor lists Kaitoi in its MCP settings and asks you to sign in.
Complete the sign-in in the browser.

## VS Code and GitHub Copilot

Open the Command Palette and run **MCP: Add Server**. Choose HTTP, paste the
server URL and name it `kaitoi`.

To edit the configuration by hand instead, run **MCP: Open User
Configuration** and add:

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

VS Code asks you to sign in the first time the server starts. Complete the
sign-in in the browser. If your organization manages Copilot, an admin may need
to allow MCP servers first.

## Windsurf

Windsurf is now called Devin Desktop. Add Kaitoi to
`~/.config/devin/mcp_config.json`, or `%APPDATA%\devin\mcp_config.json` on
Windows:

```json
{
  "mcpServers": {
    "kaitoi": {
      "url": "https://mcp.studio.kaitoi.io"
    }
  }
}
```

Save it. Devin asks you to sign in the first time it uses Kaitoi. If you have
the Devin CLI, you can also sign in from a terminal with
`devin mcp login kaitoi`. In the legacy Cascade agent, you can open the same
file from the Actions menu at the top of the Cascade panel.

## Gemini CLI

Set up Gemini CLI with a static token. Create one first, as described in
[Static tokens](#static-tokens), and keep it in an environment variable:

```bash
export KAITOI_MCP_TOKEN="your token here"
gemini mcp add --transport http --scope user \
  --header "Authorization: Bearer $KAITOI_MCP_TOKEN" \
  kaitoi https://mcp.studio.kaitoi.io
```

Gemini CLI writes the token into its settings file. `--scope user` puts it in
`~/.gemini/settings.json` rather than in a `.gemini` folder inside the current
project, where it could end up committed to a repository.

Run `gemini mcp list` to confirm Kaitoi is connected.

## Zed

Open **Settings → AI → MCP Servers**, click **Add Server**, then **Add Remote
Server**, and paste the server URL. In `settings.json` the result looks like
this:

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

Zed asks you to sign in when the server has no `Authorization` header configured.
Complete the sign-in in the browser.

## Other clients

A client needs to support remote MCP servers over Streamable HTTP, and an OAuth
sign-in that works with Kaitoi. Add a remote server, name it `Kaitoi`, give it
the server URL, and complete the browser sign-in. Kaitoi supports dynamic client
registration, so clients that register themselves automatically need no client
ID or secret.

If the sign-in does not complete, and the client can send an `Authorization`
header, use a static token instead.

## Static tokens

A static token is for CI, scripts, headless machines and clients that cannot
complete a browser sign-in. Prefer OAuth everywhere else: a static token does
not renew itself, and anyone who has it can use it until it expires a year after
you create it, or until you revoke it.

To create one:

1. In Kaitoi, open **Settings → MCP → MCP Access**.
2. Click **New MCP Token**, name it after the client that will use it, and
   choose its permissions.
3. Click **Create** and copy the token. It is shown once.

Create one token per client, so you can revoke any of them without breaking the
others. Tokens only work with the MCP server. They are not
[Kaitoi Core API keys](/docs/core/quickstart/#1-get-an-api-key).

Clients send the token as a header:

```text
Authorization: Bearer <token>
```

The **MCP Setup** dialog can generate a full command or configuration with a
fresh token for most clients, under **Manual configuration with a static
token**. For Gemini CLI, use the command in the [Gemini CLI](#gemini-cli)
section rather than the generated one. To write it yourself, keep the token in
an environment variable where the client supports one.

Claude Code:

```bash
claude mcp add --transport http --scope user kaitoi https://mcp.studio.kaitoi.io \
  --header "Authorization: Bearer $KAITOI_MCP_TOKEN"
```

Codex, which reads the token from the named variable each time it connects:

```bash
codex mcp add kaitoi --url https://mcp.studio.kaitoi.io \
  --bearer-token-env-var KAITOI_MCP_TOKEN
```

Cursor:

```json
{
  "mcpServers": {
    "kaitoi": {
      "url": "https://mcp.studio.kaitoi.io",
      "headers": {
        "Authorization": "Bearer ${env:KAITOI_MCP_TOKEN}"
      }
    }
  }
}
```

## What your agent can do

Once connected, the agent has tools to:

- search the node catalogue and read a node's inputs and outputs
- run a single node, or build a graph by adding and connecting nodes, then
  validate and run it
- list, load and save your projects
- import a file from a URL into your Kaitoi storage and use it as an input
- fetch the images, video, audio, 3D models and text a run produced
- on plans with raw code editing, write new node types

Runs started this way are billed to your Kaitoi account, the same as runs
started on the canvas. Kaitoi does not stop paid runs for your review. Some
quick single-node runs return a cost preview that the agent has to confirm, but
it can confirm without asking you, and other runs, including graph runs, start
without one. Many clients can ask you to approve each tool call; turn that on if
you want to see runs before they start. For an agent that can explore but never spend your credits, grant
it only the read permission.

Ask for Kaitoi by name the first few times, for example "use Kaitoi to find an
image upscaler". Some clients otherwise reach for a web search.

## Disconnecting

- **OAuth clients**: open **Settings → MCP → MCP Access**, find the client under
  **Connected Apps**, and click **Disconnect**. To change a client's
  permissions, disconnect it and connect it again: you choose them afresh on
  the **Authorize access** page.
- **Static tokens**: find the token under **Access Tokens** on the same page.
  You can change its permissions there, or revoke it.

Remove Kaitoi from the client's own settings as well, or it will keep trying to
reconnect.

## Troubleshooting

**The MCP settings page says it is available in Indie.** Your account does not
have MCP access. Check your plan: MCP access is included from Indie up.

**The client reports an invalid token or keeps asking to reconnect.** With
OAuth, clear the client's saved Kaitoi sign-in and connect again. In Claude
Code, run `/mcp`, select `kaitoi` and clear its authentication. In Codex, run
`codex mcp logout kaitoi` and then `codex mcp login kaitoi`. Elsewhere, remove
the server and add it again. With a static token, check the token and any
environment variable the client reads it from. If the token has expired or been
revoked, create a new one under **Access Tokens** and update the client.

**The agent can read but cannot run anything.** Check that the connection has
the write permission. For an OAuth client, disconnect it under **Connected Apps**,
connect it again and leave the second permission ticked. For a static token,
add the permission under **Access Tokens**. If write is already granted, check
the client's own tool settings and the error the run returned.

**The agent says Kaitoi is unavailable, or searches the web instead.** Check the
connector is switched on for the conversation, then mention Kaitoi by name. In
ChatGPT, pick it with `@`.

## Current limitations

- ChatGPT connects with OAuth only. So does Claude, apart from organizations
  with its request header beta.
- Gemini CLI is set up with a static token rather than a browser sign-in.
- Static tokens do not renew. Each one expires a year after you create it, so
  replace it before then, and revoke any token you no longer use.