Connect your coding agent

Connect Kosuke to your coding agent, and it can start chat sessions, follow a turn and open the pull request for you. Kosuke 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 Kosuke.

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

Sign in and allow the app

The first time your client calls Kosuke, it opens your browser. Sign in, then allow the app on Kosuke's consent screen. The app can then read and change projects, chat sessions and deploys in every workspace you belong to, as you.

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, exactly like an API key, and the app renews it for as long as it stays connected.

To see the apps you have allowed, open Settings > Your Account > 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 Kosuke and paste https://app.kosuke.ai/api/mcp as the URL.
3. Connect it, and sign in when Kosuke asks.

This link opens the dialog with both fields filled in:

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:

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:

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 instead, the same one the CLI uses:

Authorization: Bearer kosuke_…

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

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

{
  "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 Kosuke, 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 Kosuke 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 all 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 configured preview domain, such as previews.stage.kosuke.ai on stage or previews.kosuke.ai in production. 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 Kosuke.

Files and deploy messages

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

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

The deploy_run tool starts a Deploy, or sends the deploy agent a message as userResponse, but cannot attach files. Use kosuke deploy run <projectId> --content "…" --attach <path> for that.

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

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

read_only=true also leaves out preview_get and preview_shared, 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 Kosuke does not know, or a read_only value other than true or false, gets 400 with the valid values.

Toolsets

The server offers 182 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	48	Chat sessions: create, start, send, Up next, turns, messages, search, files, diff, comments, commits, artifacts, Session Labels, /clear and /compact
workspaces	42	Members, usage, credits, AI providers and their logins, skills, plugins, sandboxes, Integrations and the Slack Bot
user	22	Your account: profile, Personal Skills, Personal Plugins, Subscriptions and your Default Model
projects	22	Projects and their settings: services, environment variables, import, skills, branches, Session Labels
deploy	12	Start, stop, list and read Deploys, pick the deploy model, and manage the Deploy Chat's Up next
preview	8	Preview addresses, health, reset, share links and shared artifacts
crons	15	A workspace's crons: create, change, pause, fire once, resume a paused project, delete, and read or stop their runs
composite	3	ship, watch and submit
voice	7	Spoken summaries, read receipts, clarification answers, Steer, session creation, projects and Cron Runs
github	2	Your GitHub Connection and the repositories it reaches
models	1	The models a chat session can use

Meta connector

Use the voice toolset for the Meta connector:

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

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

The seven 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_needs_you, 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 or Kimi Code 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 Kosuke'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
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

• Kosuke CLI
• Build an agent on Kosuke
• Ship a change end to end