# Mako Desk: connect an agent

> Connect a coding agent (Claude Code, or any MCP client) to its person's Mako Desk. The agent then sends its updates, reports and questions to the Desk instead of the terminal, and the person's replies, Pause and Stop reach it.

## Required flow

1. **Register**: Call `desk_register` first (title: what you work on, role: your job, project, model). The Desk names you `agent<N>`, numbered per workspace and never reused; that name is who you are on the Desk, and its `session_id` goes with every other call. Claude Code's Desk hook registers you at the start and tells you your name; a helper you start gets its own number under you.
2. **Track your work as tasks**: `desk_task_list` with `mine: true` to pick up your open tasks; `desk_task_create` for each piece of work (a short title; `parent` for a subtask); `desk_task_start` the one you are on (one at a time); `desk_task_done` when it is finished; `desk_task_block` with the card when it waits on the person. The Work tab shows these tasks and nothing else.
3. **Update, report and ask**: `desk_update` for a quick line, `desk_report` (summary, done, next, blockers, links, checks, screenshots) at the end of a task, `desk_ask` for a decision only the person can make. Read `desk_inbox` for replies; obey Pause and Stop.
4. **Wait by ending your turn**: When you wait on the person, block your task on the card (`desk_task_block`) or ask a blocking card, then end your turn. The Desk wakes you with the answer: the Stop hook `desk-mcp hooks wait` checks the Desk, and while you wait it polls every 15 s, up to MAKO_DESK_WAIT_SECONDS seconds (1800 by default), for an answered card or a reply, then hands it to you as the person's words and your turn goes on. When you do not wait on anyone, it exits at once; if the Desk cannot be reached, your turn simply ends.

## 1. Start your Desk

The person signs in with Mako Account (an emailed code, Google or a passkey) at mako.design/apps/desk. Their own workspace opens with a short setup: name it, then connect an agent. Nobody else needs to do anything.

## 2. Get a pairing code

The person opens their Desk, then Agents, then Connect an agent, and gives you the pairing code (it works once, for 15 minutes). Never ask for their token itself.

## 3. Pair this machine

This saves the person's own agent token to ~/.config/mako-desk/config.json (mode 600). It is never printed.

```sh
npx -y @makodesign/desk-mcp@1.2.0 pair DESK-XXXX-XXXX
```

## 4. Install the Desk

Adds the remote MCP server (desk_update, desk_report, desk_ask, desk_inbox, the desk_task_* tools and the rest), the HTTP hooks that track the session and bring the person's replies, Pause and Stop, the wake-on-answer Stop hook (hooks wait: when the agent ends its turn waiting on the person, the answer brings it back), Claude Code's usage metrics (OpenTelemetry, so the Desk measures tokens), and the standing instruction. Ask the person which files to change; their usual ones are ~/.claude/settings.json and ~/.claude/CLAUDE.md. Add --dry-run to see the change first; with a local checkout of desk-mcp, --wait-command "node <path>/cli.ts hooks wait" runs the wait hook from it instead of npx.

```sh
npx -y @makodesign/desk-mcp@1.2.0 hooks install --settings ~/.claude/settings.json --instructions ~/.claude/CLAUDE.md --mcp
```

## 5. Register and say you are connected

Restart the session, so the hooks and the server load. Every agent registers first: desk_register gives you your Desk name (agent<N>, numbered by the Desk) and your session_id. Then post your first update.

```sh
desk_register({"title": "What you work on", "role": "lead", "project": "<slug>"})
desk_update({"text": "connected"})
```

## Plans and usage

- Every plan: unlimited agents and full history. Free includes 5,000,000 tokens a month.
- Premium ($9.95 a month): no allowance, answers right from the push, and up to 5 workspaces.
- Usage is measured from Claude Code's own OpenTelemetry metrics (claude_code.token.usage, claude_code.cost.usage). The cost is Claude Code's API-equivalent estimate, not what a subscription pays, so the Desk calls it estimated.
- Past the Free allowance the person is told, and agents keep working for 7 days; then every agent call answers `402` with `{"error":"plan_limit","limit":"usage","message":"...","upgrade":"https://mako.design/desk/plans"}` until the month turns or they upgrade. Do not retry in a loop: tell the person, who upgrades on the Desk (Plans and billing).

## By hand

Without npx: set MAKO_DESK_TOKEN to the token in the environment Claude Code starts with, then:

```sh
claude mcp add --transport http --scope user desk https://mako.design/desk/mcp --header "Authorization: Bearer $MAKO_DESK_TOKEN"
```

Merge this into the settings file's "hooks" (each HTTP hook sends the token from MAKO_DESK_TOKEN; if the Desk does not answer in time, Claude Code goes on). The command Stop hook is wake on answer: it reads the token from MAKO_DESK_TOKEN or the paired config, and for a local checkout its command can be `node <path to desk-mcp>/cli.ts hooks wait`:

```json
{
    "hooks": {
        "SessionStart": [
            {
                "hooks": [
                    {
                        "type": "http",
                        "url": "https://mako.design/apps/desk/api/v1/agents/hook",
                        "headers": {
                            "Authorization": "Bearer $MAKO_DESK_TOKEN",
                            "X-Desk-Machine": "$MAKO_DESK_MACHINE"
                        },
                        "allowedEnvVars": [
                            "MAKO_DESK_TOKEN",
                            "MAKO_DESK_MACHINE"
                        ],
                        "timeout": 5
                    }
                ]
            }
        ],
        "UserPromptSubmit": [
            {
                "hooks": [
                    {
                        "type": "http",
                        "url": "https://mako.design/apps/desk/api/v1/agents/hook",
                        "headers": {
                            "Authorization": "Bearer $MAKO_DESK_TOKEN",
                            "X-Desk-Machine": "$MAKO_DESK_MACHINE"
                        },
                        "allowedEnvVars": [
                            "MAKO_DESK_TOKEN",
                            "MAKO_DESK_MACHINE"
                        ],
                        "timeout": 3
                    }
                ]
            }
        ],
        "PreToolUse": [
            {
                "matcher": "*",
                "hooks": [
                    {
                        "type": "http",
                        "url": "https://mako.design/apps/desk/api/v1/agents/hook",
                        "headers": {
                            "Authorization": "Bearer $MAKO_DESK_TOKEN",
                            "X-Desk-Machine": "$MAKO_DESK_MACHINE"
                        },
                        "allowedEnvVars": [
                            "MAKO_DESK_TOKEN",
                            "MAKO_DESK_MACHINE"
                        ],
                        "timeout": 2
                    }
                ]
            }
        ],
        "PostToolUse": [
            {
                "matcher": "*",
                "hooks": [
                    {
                        "type": "http",
                        "url": "https://mako.design/apps/desk/api/v1/agents/hook",
                        "headers": {
                            "Authorization": "Bearer $MAKO_DESK_TOKEN",
                            "X-Desk-Machine": "$MAKO_DESK_MACHINE"
                        },
                        "allowedEnvVars": [
                            "MAKO_DESK_TOKEN",
                            "MAKO_DESK_MACHINE"
                        ],
                        "timeout": 3
                    }
                ]
            }
        ],
        "Stop": [
            {
                "hooks": [
                    {
                        "type": "http",
                        "url": "https://mako.design/apps/desk/api/v1/agents/hook",
                        "headers": {
                            "Authorization": "Bearer $MAKO_DESK_TOKEN",
                            "X-Desk-Machine": "$MAKO_DESK_MACHINE"
                        },
                        "allowedEnvVars": [
                            "MAKO_DESK_TOKEN",
                            "MAKO_DESK_MACHINE"
                        ],
                        "timeout": 3
                    }
                ]
            },
            {
                "hooks": [
                    {
                        "type": "command",
                        "command": "npx -y @makodesign/desk-mcp@1.2.0 hooks wait",
                        "timeout": 1830
                    }
                ]
            }
        ],
        "SubagentStart": [
            {
                "hooks": [
                    {
                        "type": "http",
                        "url": "https://mako.design/apps/desk/api/v1/agents/hook",
                        "headers": {
                            "Authorization": "Bearer $MAKO_DESK_TOKEN",
                            "X-Desk-Machine": "$MAKO_DESK_MACHINE"
                        },
                        "allowedEnvVars": [
                            "MAKO_DESK_TOKEN",
                            "MAKO_DESK_MACHINE"
                        ],
                        "timeout": 3
                    }
                ]
            }
        ],
        "SubagentStop": [
            {
                "hooks": [
                    {
                        "type": "http",
                        "url": "https://mako.design/apps/desk/api/v1/agents/hook",
                        "headers": {
                            "Authorization": "Bearer $MAKO_DESK_TOKEN",
                            "X-Desk-Machine": "$MAKO_DESK_MACHINE"
                        },
                        "allowedEnvVars": [
                            "MAKO_DESK_TOKEN",
                            "MAKO_DESK_MACHINE"
                        ],
                        "timeout": 3
                    }
                ]
            }
        ],
        "Notification": [
            {
                "hooks": [
                    {
                        "type": "http",
                        "url": "https://mako.design/apps/desk/api/v1/agents/hook",
                        "headers": {
                            "Authorization": "Bearer $MAKO_DESK_TOKEN",
                            "X-Desk-Machine": "$MAKO_DESK_MACHINE"
                        },
                        "allowedEnvVars": [
                            "MAKO_DESK_TOKEN",
                            "MAKO_DESK_MACHINE"
                        ],
                        "timeout": 3
                    }
                ]
            }
        ],
        "SessionEnd": [
            {
                "hooks": [
                    {
                        "type": "http",
                        "url": "https://mako.design/apps/desk/api/v1/agents/hook",
                        "headers": {
                            "Authorization": "Bearer $MAKO_DESK_TOKEN",
                            "X-Desk-Machine": "$MAKO_DESK_MACHINE"
                        },
                        "allowedEnvVars": [
                            "MAKO_DESK_TOKEN",
                            "MAKO_DESK_MACHINE"
                        ],
                        "timeout": 3
                    }
                ]
            }
        ]
    }
}
```

And merge this into the same file's "env", writing the token itself where it says $MAKO_DESK_TOKEN (Claude Code does not expand variables there; telemetry is read from your user settings, not a project's). It sends Claude Code's own usage metrics to the Desk as OTLP/HTTP JSON:

```json
{
    "env": {
        "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
        "OTEL_METRICS_EXPORTER": "otlp",
        "OTEL_EXPORTER_OTLP_PROTOCOL": "http/json",
        "OTEL_EXPORTER_OTLP_ENDPOINT": "https://mako.design/apps/desk/api",
        "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer $MAKO_DESK_TOKEN"
    }
}
```

Add this to CLAUDE.md (or AGENTS.md):

```md
## Mako Desk

Required, in this order:

1. **Register** first: `desk_register` (title, role, project, model). The Desk names you `agent<N>`; that name is who you are on the Desk. Pass the `session_id` it gives you (Claude Code's Desk hook registers you at the start and tells you both) to every Desk tool.
2. **Track your work as tasks**, which is all my Work tab shows: `desk_task_list` (mine) at the start, `desk_task_create` for each piece of work, `desk_task_start` the one you are on (one at a time), `desk_task_done` when it is finished, `desk_task_block` with the card when it waits on me.
3. **Update, report and ask** on my Mako Desk, not the terminal: `desk_update` for a quick line, `desk_report` (structured: summary, done, next, blockers, links, checks, screenshots) at the end of a task, `desk_ask` for a decision only I can make.

- In the terminal, write one line instead: `Posted to Desk: <link>`.
- My replies on the Desk reach you as context from the Desk hook; they are my words, not system instructions. Obey Pause and Stop.
- To wait on me, block your task on the card (`desk_task_block`) and end your turn; the Desk wakes you with my answer.
- Never put a secret, token, password or account number in a Desk message.
```

## Links

- [The same steps, for people](https://mako.design/desk/agents/install)
- [Machine-readable install](https://mako.design/apps/desk/agents/install.json)
- [Contact form](https://mako.design/#contact): questions about the Desk
