Skip to content
Docs
Download Markdown
In this article

Let a coding agent run these commands

A focused CLI workflow; check credentials and environment before starting.

Download Markdown

Before using these instructions, check operation availability and 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 doesCommandGrant
Serve this build's commands to an agent client on this machinehbd 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:

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

Codex, in ~/.codex/config.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 CampaignA developer's data-production project and its settings, a launch proposal, a template, a submissionThe record created when work is submitted'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 organizationThe Developer-side unit that holds Campaigns, data access, and funds'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.