mcp-server

harness install mcp-server

The mcp-server package makes The Harness an MCP server: harness mcp. An MCP client (an app such as Cursor, ChatGPT or Claude, or an agent such as Claude Code, Codex, OpenCode or Pi) then gives The Harness tasks on this computer (in a browser, on the desktop, in its apps) and follows them. Each task is a session of the user's session host, so the app and the terminal chat (/sessions) list and follow it as well.

Install

harness install mcp-server

It needs nothing outside Python.

Use

harness mcp speaks MCP on stdin and stdout, which is what an MCP client starts. harness mcp --http [--port 8790] serves streamable HTTP at http://127.0.0.1:8790/mcp instead; it answers requests from this computer only.

Claude Code:

claude mcp add harness -- harness mcp
# or, with harness mcp --http running:
claude mcp add --transport http harness http://127.0.0.1:8790/mcp

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

[mcp_servers.harness]
command = "harness"
args = ["mcp"]

Cursor, in .cursor/mcp.json:

{"mcpServers": {"harness": {"command": "harness", "args": ["mcp"]}}}

Tools

Tool	Does
run_task {task, workspace?, wait_seconds?}	Starts a session on the task and waits at most wait_seconds (default 30, at most 120) for its answer; a longer task returns its session id and progress, to poll with get_session.
start_session {task, workspace?}	Starts a session and returns at once.
list_sessions {all?}	The sessions, newest first.
get_session {session, lines?}	Its status, what it waits for, its answer and its last lines of progress.
send_message {session, text}	A message for the session's agent.
stop_session {session}	Ends the session.
observe_screen {session}	The screen of its workspace now, as an image.
read_events {session, after?, limit?}	Its trace records, compact, with next_after for paging.
list_packages {query?}	The installed packages, or the registry's that match.
install_package {name}	Installs an official package by name.
list_library {name?}	The libraries of what the agent learned, or one library's entries.

workspace names a kind supplied by an explicitly installed package. Pass folder to bind a project directory, and optional budget (max_wall_seconds, max_model_calls, max_cost_usd) to bound the task. auto resolves the binding through installed providers. Missing capabilities are reported; no app, agent or workspace is installed by default.

Approvals

A session may wait for the user's approval: a program to confirm, or a step of physical input that the physical-input policy holds. The tools report that it waits; the user approves it in a harness frontend (the app, or /approve in the terminal chat). There is no approve tool, so the agent that calls the tools never approves its own input.

0.2.2

• A conversation goes on until you end it. The agent's answer, a reply in plain text, ends its turn, not the conversation: the next message goes to the same conversation, which keeps its messages, the variables of its programs, its rules, its facts and the environment. What the agent left running goes on after the answer, and the end of a unit or an event starts its next turn without a message. Model calls and time are limits of a turn and begin anew with the next one; a turn that reaches one, fails or is cancelled (/cancel) ends with that reason and the conversation waits; cost is counted for the whole conversation. Every turn ends with a turn_result record. /clear is another name of /new. Sessions are kept on disk as they go (conversation.json beside the trace), and one that ended is continued in its own session id with a new kernel: harness --continue, harness --resume ID, harness run --continue | --session ID "task", harness sessions resume ID, /resume, Host.resume_session(); what lived in the old process (variables, rules, running programs) is gone, and the agent is told so. A sub-agent whose turn ended can be sent another message (send_agent) and goes on with its history. A conversation whose workspace is needed by another is parked, and its next message continues it. A run nobody talks to keeps its conversation as well: harness program CONFIG --continue EPISODE --message "..." gives the episode in that directory one more turn, in its own session, against the worker that runs. What breaks: the prompt no longer teaches <finish>; <finish> and finish() are still accepted and mean the same as a text answer. In a run without a user (a benchmark), a reply in plain text now ends the run as its answer instead of being sent back as a format error. A frontend that waited for FINISHED after an answer waits for the turn_result record instead (the state after it is IDLE, whose reason is how the turn ended); harness run "task" and the MCP server's run_task still end the session they started after its turn. A sub-agent's report has no question and no asks status: what it asks is its answer. ACP session/cancel ends the turn and keeps the conversation. A task the agent package gives (harness agent) ends with its turn, so a question it asks comes back as the task's answer. In summary.json, a conversation closed between turns keeps the status of its last turn; closed is a turn that was cut short. The evaluator's outcome is read when the conversation ends, as before, since a worker evaluates once. A kernel that dies ends the conversation; it is continued with --resume. Esc in the terminal chat still pauses.

0.2.1

• The package summary and the help of harness mcp say who it is for: apps, editors and agents that are MCP clients.

0.2.0

• run_task and start_session accept an explicit project folder and task budget. Workspace names come from installed providers, without a product allowlist or automatic installation. Requires Harness 0.78 or later.

Unreleased (S7)

• A session that waits for approval says the user approves it in the app or with /approve in the terminal chat (harness sessions is gone).

0.1.0

• First release: harness mcp, The Harness as an MCP server on stdio or streamable HTTP (127.0.0.1), with the tools run_task, list_sessions, start_session, send_message, stop_session, get_session, observe_screen, read_events, list_packages, install_package and list_library. A session that waits for the user's approval is reported, never approved: the user approves it in a harness frontend.