# MCP

> Give any agent that speaks MCP four tools to notify you and ask you, through the remote server at usekabu.com/mcp or kabu mcp on your computer.

Kabu's MCP server gives an agent four tools: one to tell you something, and three to ask you and wait for the answer.
Connect it in one of two ways:

- **`kabu mcp` on your computer**, started by the agent as a stdio server. It signs in with the key `kabu login
  --device` saved, so no key goes in the agent's configuration. Use this for coding agents on your own machine.
- **The remote server at `https://usekabu.com/mcp`** (streamable HTTP), with an API key as a bearer token. Use this
  where nothing can be installed, or from a hosted agent.

Both serve the same tools, with the same rules: the key decides what the agent may do, and an agent's key can ask
you but never answer for you.

## Tools

| Tool | What it does |
|---|---|
| `notify_human` | Sends you a notification: `title` and `message`, with optional `fields`, `links`, `attachments`, `priority` and the `project` and `agent` it comes from |
| `ask_human` | Asks you, with `ask`: a confirm (approve or reject), a choice, a typed answer or a short form. Waits for your answer, 25 seconds or up to `max_wait_seconds`, and returns it, or the ask's `id` while it is still open |
| `wait_for_human_answer` | Waits for the ask with this `id`, as long as `ask_human` does; call it again until the ask settles |
| `upload_file_for_human` | Gets an upload URL for a file (`filename`, `content_type`, `size`, `sha256`), to attach to a notification or an ask. The file's bytes never pass through the model |

Each tool's arguments are the matching fields of the API request it makes, such as
[create a message](/docs/api/messages#messages.create), and each tool's schema says them in full. Every tool but
`wait_for_human_answer` takes an `idempotency_key`: calling again with the same key returns the first call's result
instead of doing it twice.

The `kabu_*` tools from before these four were retired on 31 October 2026: calling one gets the JSON-RPC error
`-32602`, unknown tool.

## Waiting for your answer

`ask_human` and `wait_for_human_answer` wait 25 seconds unless `max_wait_seconds` asks for longer, up to an hour
(3600), and never past the ask's expiry. They return as soon as you answer, so an agent can pass 3600 to wait until
you reply.

A wait over 25 seconds answers as an event stream. If the call carries a progress token, a progress notification
arrives about every 15 seconds, so a client that resets its timeout on progress keeps the call open. If the call
is cut anyway, nothing is lost: each progress message names the ask's `id` for `wait_for_human_answer`, and
`ask_human` called again with the same `idempotency_key` resumes the same ask.

## Local: kabu mcp

Install the CLI and log in ([Quickstart](/docs/quickstart)), then register `kabu mcp` as a stdio server.

Claude Code:

```sh
claude mcp add kabu -- kabu mcp
```

Anywhere a JSON configuration lists MCP servers (Cursor's `~/.cursor/mcp.json`, for one):

```json
{
  "mcpServers": {
    "kabu": { "command": "kabu", "args": ["mcp"] }
  }
}
```

Claude Code and GitHub Copilot CLI get this server with the [plugin](/docs/plugin), already registered.

`kabu mcp` passes each message to `https://usekabu.com/mcp` and each reply back, one line each. It retries nothing, so
a tool call is never sent twice; a call that fails gets an error for its id. It exits when the agent closes it.

## Remote: usekabu.com/mcp

Create an API key in the console, keep it in your environment, and point the client at the server:

```sh
export KABU_API_KEY="kabu_live_sk_…"
claude mcp add --transport http kabu https://usekabu.com/mcp --header "Authorization: Bearer $KABU_API_KEY"
```

Cursor reads the key from the environment:

```json
{
  "mcpServers": {
    "kabu": {
      "url": "https://usekabu.com/mcp",
      "headers": { "Authorization": "Bearer ${env:KABU_API_KEY}" }
    }
  }
}
```

Codex, in `~/.codex/config.toml`:

```toml
[mcp_servers.kabu]
url = "https://usekabu.com/mcp"
bearer_token_env_var = "KABU_API_KEY"
```

Check the connection with a raw request. A `401` means the key is missing or revoked:

```sh
curl -sS https://usekabu.com/mcp \
  -H "Authorization: Bearer $KABU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
```

## Who is asking

Pass `project` (the repository or service) and `agent` (your agent's name, such as `claude-code`) on every call, so
you know who is asking and about what. Without them, Kabu takes the agent's name from the client's MCP handshake and
the project from the client's first workspace folder, when the client shares one. A key bound to a project or an
agent always sends as that project or agent.

## Tell your agent when to ask

Add a rule like this to your agent's instructions (for example `AGENTS.md`):

```markdown
Before an irreversible or production-affecting action (a deploy, a migration, deleting data), call ask_human with a
short title, what will run, ask.type "confirm" and max_wait_seconds 3600. If it returns an id instead of an answer,
call wait_for_human_answer with that id until it settles. Go ahead only when the decision is "approve". Use
notify_human when a long job finishes or fails.
```