# Let a coding agent run these commands


> Before using these instructions, check [operation availability and compatibility](/api/compatibility).

A build that lists `hbd mcp serve` in `hbd --help --json` can hand its commands to an agent client on the same machine, such as Claude Code or Codex. The client starts `hbd mcp serve --stdio` and talks to it over standard input and output, so there is no server address to connect to. Humanbased runs no hosted MCP server.

| What it does | Command | Grant |
| --- | --- | --- |
| Serve this build's commands to an agent client on this machine | `hbd mcp serve --stdio` | — |

Each command becomes one tool, named after the command with underscores: `campaign_list` runs `hbd campaign list`, and `campaign_versions_inspect` runs `hbd campaign version show`. A tool takes the command's own arguments under the same names, such as `campaign-id`, `limit` and `idempotency-key`, and returns the envelope that `--json` prints. Its `error` is `null` only when the command succeeded.

Commands a person has to finish are not offered: signing in and out, revoking a session, and running a confirmed launch.

## Connect a client

Each call uses the credential the same command would use at your terminal: `HB_API_KEY` when it is set in the server's environment, otherwise the session that `hbd auth login` saved for the server's profile. The `--profile` and `--timeout` options given to `hbd mcp serve` apply to every call.

Claude Code:

```sh
claude mcp add --transport stdio humanbased -- humanbased mcp serve --stdio
claude mcp get humanbased
```

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

```toml
[mcp_servers.humanbased]
command = "humanbased"
args = ["mcp", "serve", "--stdio"]
default_tools_approval_mode = "writes"
```

## Approve what changes

Tools marked read-only change nothing on the server. The others change something: a Campaign, a launch proposal, a template, a submission's verdict, an Academy course draft or a grade on a contributor's answer, an uploaded file, or a profile on this machine. Claude Code asks you before every call to one of them, even when its permission mode would otherwise allow it, except the Academy course commands, `files upload` and `campaign input import`. An agent may write a course draft, submit it for review and grade its open answers, upload an image, or import one of the organization's datasets into a Campaign without asking you (through MCP, only into a draft or paused Campaign; a person imports into a live one at a terminal), so Claude Code asks before those only when its own permission settings say to. With `default_tools_approval_mode = "writes"`, Codex asks before every tool not marked read-only, these included.

A saved CLI session writes in the organization approved at sign-in, so it needs no `--org`. With an API Key, start the server with `--org <organization-id>`, set `HB_ORG`, or pass `org` on each write. An explicit organization that differs from the credential is refused with `ORG_MISMATCH` before the write is sent.

## Files, paths and waiting

Through MCP, `campaign init`, `template init` and `campaign plan` write no file: the document comes back as `data.artifact`. Save it where you want it, then pass that path to `campaign validate` as `file`, or to `campaign apply` as `plan`. Other commands return in `data` what their `--out` would have written.

Standard input carries the protocol, so a file argument of `-` is refused; give a path. A relative path is read from the directory the client started the server in.

Through MCP, `files upload` takes only an image (PNG, JPEG, WebP, GIF, HEIC, HEIF, AVIF, TIFF or BMP), judged by the file's first bytes and never by its name. Any other file is refused before the rest of it is read or anything is sent. A file uploaded as `campaign` or `cover` is public to anyone with its address.

`campaign records pull` returns one page per call, as the command's own JSON text, so every digit of a record's numbers is kept. For the next page, pass `data.next_cursor` back as `cursor` and `data.subscription_id` as `subscription`. For a whole export in one run, use the command at a terminal with `--all`.

The server runs one call at a time. No call waits on a server job for more than 45 seconds, which keeps it inside the 60 seconds Codex allows a tool call unless `tool_timeout_sec` raises it.

`dsa_consult` returns as soon as DSA accepts the question, with the run's ID in `data.run_id`. Follow the run with `dsa_run` and `wait`, which follows it for 45 seconds at most. If the run is still going then, the answer is not an error: `data.status` is `queued` or `running`, `data.cursor` marks how far it got, and a notice names the next call, `dsa_run` with `after` set to `data.cursor`. `campaign_apply` with `wait` answers `WAIT_TIMEOUT` when its 45 seconds run out instead: the apply is still running, not failed; call again to keep following it.

A call the client cancels stops at once if it was reading or waiting. A write it had already sent finishes, since it may already have taken effect, and nothing is sent after it. If that write took an `idempotency-key`, send it again with the same key to read what it did; it is not done twice.

When the client ends the session, the server stops the call in progress the same way and exits; calls still queued behind it do not start.
