# Connect your coding agent

Connect Sensei to your coding agent, and it can start chat sessions, follow a turn and open the pull request for you. Sensei hosts the MCP server, so there is nothing to install or keep running. Add one URL to your client, sign in, then ask your agent to use Sensei.

```text
https://app.kosuke.ai/api/mcp
```

[Integrate Kosuke](https://kosuke.ai/docs/integrate.md) puts this URL, the CLI, an API key and one prompt for your agent on one page.

## Sign in and allow the app

The first time your client calls Sensei, it opens your browser. Sign in, then allow the app on Sensei's consent screen. The app can then read and change projects and tasks, and read deploys, in every workspace you belong to, as you. It cannot change a project's setup, services or environment, or start a deploy: see [Settings and deploys](https://kosuke.ai/docs/interfaces/mcp.md#settings-and-deploys).

The consent screen shows the app's name and, under it, the site that publishes its details, such as `claude.ai`. For an app that registered itself, it shows the address the app sends you back to instead, marked **Unverified app**.

Once you allow it, the app is a Connected App and holds a Connector Token. The token acts as you, like an [API key](https://kosuke.ai/docs/api/authentication.md), and the app renews it for as long as it stays connected. It reaches what your API key reaches, your Sensei Chat, [personal Files](https://kosuke.ai/docs/workspace/files.md#personal-files) and Personal Crons included.

To see the apps you have allowed, open Settings > You > API keys and find **Connected apps**. Press **Disconnect** to cut an app off. Its next call is refused.

## Claude

1. Open Settings, then **Connectors**, then **Add custom connector**.
2. Name it `Sensei` and paste `https://app.kosuke.ai/api/mcp` as the URL.
3. Connect it, and sign in when Sensei asks.

This link opens the dialog with both fields filled in. It fills in the name Kosuke; rename it Sensei there if you like, since the name is only your label:

```text
https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Kosuke&connectorUrl=https%3A%2F%2Fapp.kosuke.ai%2Fapi%2Fmcp
```

On the Free plan, this is your one custom connector. On Team and Enterprise, an Owner adds it once for the whole workspace. Everyone else then connects it with their own account from the same dialog.

## Claude Code

Run this once:

```sh
claude mcp add --transport http kosuke https://app.kosuke.ai/api/mcp
```

Start Claude Code and type `/mcp` to sign in. The list then shows `kosuke` as connected.

## ChatGPT and Codex

In ChatGPT, open Settings, then **Developer mode**, then **Add server**, and paste `https://app.kosuke.ai/api/mcp` as the URL.

In Codex, run:

```sh
codex mcp add kosuke --url https://app.kosuke.ai/api/mcp
codex mcp login kosuke
```

To check it, run `codex mcp list`. It shows `kosuke` with its URL.

## Cursor and other clients

Any MCP client that supports Streamable HTTP and OAuth needs only the URL. It opens your browser to sign in at the first call, as Claude and Codex do.

## Without a browser

A script, the Agent SDK, the Claude Messages API or the OpenAI Responses API has no browser to sign in from. Send an [API key](https://kosuke.ai/docs/api/authentication.md) instead, the same one the CLI uses:

```http
Authorization: Bearer kosuke_...
```

Each tool call is checked against the key's access, so a tool outside it is refused with 403 `API_KEY_SCOPE`. The `voice` toolset, and `all`, which includes it, need a Full access key.

The Claude Messages API takes the key as `authorization_token` on the server entry, with the `anthropic-beta: mcp-client-2025-11-20` header:

```json
{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://app.kosuke.ai/api/mcp",
      "name": "kosuke",
      "authorization_token": "kosuke_..."
    }
  ]
}
```

The OpenAI Responses API's `mcp` tool takes it as `authorization`:

```json
{
  "tools": [
    {
      "type": "mcp",
      "server_label": "kosuke",
      "server_url": "https://app.kosuke.ai/api/mcp",
      "authorization": "kosuke_...",
      "require_approval": "never"
    }
  ]
}
```

## Try it

Ask your agent in plain words. For example:

- "Using Sensei, start a session in the storefront project that fixes the typo on the pricing page. Watch it until the turn ends and tell me what changed."
- "Open the pull request for my Sensei session about the pricing typo, then tell me when it is ready."

## Shortcut tools

Three tools cover the common flow, so your agent does not have to carry ids from one call to the next.

| Tool | What it does |
| --- | --- |
| `ship` | Creates a chat session from a prompt and starts it, or starts a Backlog session. Returns the turn to watch |
| `watch` | Follows a turn, or the project's deploy, until it ends or its timeout passes, 50 seconds by default. Returns the final status, the agent's last message and a preview link when the turn ends. Call it again to keep waiting |
| `submit` | Sends the `kosuke:open-pr` skill to a session (`/kosuke:open-pr` on Claude, `$kosuke:open-pr` on Codex), which opens or updates its pull request. Returns the turn to watch |

Every other tool, except the voice tools, matches a CLI command. `kosuke sessions send` is the tool `sessions_send`, and its flags are the tool's arguments. `kosuke sessions list` with no project and `kosuke activity list` have no tool.

When `watch` returns `done: true`, `previewUrl` is the first direct service URL from preview health. `frontendUrls` contains the URL of every preview endpoint, keyed by its service name, or by `<service>-<endpoint>` for a service's second and later endpoints. These URLs use the preview domain, `previews.kosuke.ai`. A deploy uses the project's main sandbox.

If the sandbox is paused, has no preview services, or the lookup fails, `previewUrl` is `null` and `frontendUrls` is empty. Returning URLs does not wake the sandbox or create a public share link. Direct URLs require the existing preview authentication cookie, established by opening the preview in Sensei.

## Files

The tools take no attachments, because the server cannot read files on your machine. To send a file, use the CLI's `--attach`:

```sh
kosuke sessions create <projectId> --content "Match this screenshot" --attach shot.png
```

## Settings and deploys

An app holds a Connector Token, and a Connector Token cannot change a project's setup, services or environment, import a config, or start or answer a Deploy. These tools get 403 `SETTINGS_ADMIN_ONLY`, for an admin too, until API keys get a project settings scope:

- `projects_settings_update`, except for the QA Guide (`qaGuide`) and the device folders (`deviceWritePaths`)
- `projects_settings_set`
- `projects_services_create`, `projects_services_update` and `projects_services_delete`
- `projects_env_vars_create` and `projects_env_vars_delete`
- `deploys_start`

A workspace admin makes these changes in the project's settings and its Deploy Chat. See [Project settings](https://kosuke.ai/docs/set-up/project-settings.md#who-can-change-them). The app still reads the settings with `projects_settings_get` and their Change history with `projects_settings_changes_list`.

## Options

Add options to the URL as query parameters.

| Parameter | Default | What it does |
| --- | --- | --- |
| `toolsets=<names>` | `core` | Loads only the toolsets you name, separated by commas. `all` loads every tool |
| `read_only=true` | `false` | Loads only the tools that read and leave sandboxes asleep |

```text
https://app.kosuke.ai/api/mcp?toolsets=sessions,composite
```

`read_only=true` also leaves out `preview_get` and `preview_shared_get`, because they wake a paused sandbox and start billing. It leaves out `sessions_files_get` too. A client that trusts a tool's read-only mark to skip asking you follows the same rule.

A toolset name Sensei does not know, or a `read_only` value other than `true` or `false`, gets 400 with the valid values.

## Toolsets

The server offers 250 tools. With no `toolsets`, your agent gets `core`, the 18 tools most changes need. Load more with `toolsets`, or every tool with `toolsets=all`.

| Toolset | Tools | Covers |
| --- | ---: | --- |
| `core` | 18 | `ship`, `watch` and `submit`, the common reads and writes for projects, sessions, deploys and previews, `models_list` and `workspaces_list` |
| `sessions` | 59 | Chat sessions: create, start, send, Up next, turns, messages, search, sandbox files, session files, diff, comments, commits, Session Labels, QA Runs, `/clear` and `/compact` |
| `projects` | 40 | Projects and their settings: services, environment variables, Change history, skills, branches, Session Labels, the live app |
| `sensei` | 33 | The tools a Sensei Turn uses: messages, threads, reviews, merges and cards |
| `mac` | 21 | Use one of your Macs: screenshots, clicks, keys, windows, files, browser and shell |
| `providers` | 19 | Credentials and Subscriptions: workspace Credentials, your own Subscriptions, logins, usage and your Default Model |
| `crons` | 13 | Crons, a workspace's or your own: create, change, fire once, delete, and read or stop their runs |
| `deploys` | 13 | Stop, list and read Deploys, pick the deploy model, and manage the Deploy Chat's Up next |
| `workspaces` | 9 | Members, usage, credits, the timezone and sandboxes |
| `tasks` | 8 | Tasks, a workspace's or your own: create, change, move, start and delete |
| `preview` | 8 | Preview addresses, health, reset, share links and shared files |
| `files` | 6 | Files, a workspace's or your own: list, read, upload, move and delete |
| `integrations` | 6 | Integration connections, a workspace's or your own, and your LinkedIn and X connections |
| `user` | 4 | Your account: profile, API key and push devices |
| `skills` | 5 | Custom Skills, a workspace's or your own |
| `devices` | 2 | List the devices you can use, and ask for one |
| `plugins` | 2 | Plugins, a workspace's or your own |
| `github` | 2 | Your GitHub Connection and the repositories it reaches |
| `models` | 1 | The models a chat session can use |
| `composite` | 3 | `ship`, `watch` and `submit` |
| `voice` | 6 | Spoken session reads, clarification answers, Steer, session creation, projects and Cron Runs |

A tool whose command has a personal form takes `workspaceId: "personal"` for your own, as the CLI takes `personal`: `crons_get` reads a Personal Cron with `workspaceId: "personal"`. A provider's tool picks the provider by `provider`, as `providers_usage_get` does.

## Meta connector

Use the voice toolset for the Meta connector:

```text
https://app.kosuke.ai/api/mcp?toolsets=voice
```

Sign in through the same consent screen as other MCP clients. Disconnect it in Settings > You > API keys > Connected apps.

The six tools return sentences to read aloud. They preserve session references for follow-up requests and report refusals in spoken form. Before sending, repeat the destination and message unless the member already stated both clearly.

Add `&read_only=true` to keep only `list_projects` and `get_cron_runs`. This also excludes `get_chat_session`, which marks the session read.

## Safety

- Every tool that writes is marked as one, so a client that asks before risky calls asks before these.
- The server refuses Anthropic, Bedrock and OpenAI keys and secret environment variables in tool arguments. A GLM Coding Plan, Kimi Code or DeepSeek API key is not refused. Set all of these in Settings instead of pasting them into your agent.
- An argument that looks like it quotes a credential still goes through, and the result carries a warning.
- Results mask secret environment values and a project's Sentry DSN.
- A preview share link is a credential. Only `preview_share_get` and `preview_share_create` return one.
- No tool can create API keys, change billing or reach Sensei's admin pages.

## Troubleshooting

| Symptom | What to do |
| --- | --- |
| The client never opens the sign-in | Check that the URL is `https://app.kosuke.ai/api/mcp` and that the client supports OAuth. Otherwise send an API key, as in [Without a browser](https://kosuke.ai/docs/interfaces/mcp.md#without-a-browser) |
| Every tool call is refused | The app was disconnected, or the API key was revoked. Connect the app again, or create a new API key |
| The server answers 400 | A toolset name or the `read_only` value is wrong. The response lists the valid ones |
| Your agent cannot find a tool | It is outside `core`. Add its toolset to `toolsets`, or use `toolsets=all` |

## Next steps

- [Sensei CLI](https://kosuke.ai/docs/interfaces/cli.md)
- [Build an agent on Sensei](https://kosuke.ai/docs/api/build-an-agent.md)
- [Ship a change end to end](https://kosuke.ai/docs/recipes/ship-a-change-end-to-end.md)