Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

harness mcp names the next steps as its tools (#1203)

Dee3feff3d78633
diff --git a/cli/e2e/agentClient.e2e.ts b/cli/e2e/agentClient.e2e.ts
index b70324c33..4c3452766 100644
--- a/cli/e2e/agentClient.e2e.ts
+++ b/cli/e2e/agentClient.e2e.ts
@@ -243,10 +243,12 @@ describe('Harness for agents, end to end', () => {
const started = await server.call('harness_start', { task: 'hello from mcp', folder: dir, name: 'mcpkid' })
expect(started.isError, started.text).toBe(false)
expect(started.text).toContain('Created mcpkid on this computer')
+ // Its next steps are named as the tools: an MCP client may have no shell to run `harness show` in.
+ expect(started.text).toContain('Read it: harness_read (name: "mcpkid") · wait for it: harness_wait (names: "mcpkid")')
const ledger = readFileSync(join(d.dataDir, 'agent-client', 'started.jsonl'), 'utf8').trim().split('\n').map((line) => JSON.parse(line))
expect(ledger).toEqual([expect.objectContaining({ by: expect.objectContaining({ agentId: expect.stringMatching(/^agent:cursor:mcp-\d+$/), name: 'Cursor' }) })])
const waited = await server.call('harness_wait', { names: ['mcpkid'], timeout_seconds: 120 })
- expect(waited).toEqual({ text: 'mcpkid: idle · read it: harness show mcpkid', isError: false })
+ expect(waited).toEqual({ text: 'mcpkid: idle · read it: harness_read (name: "mcpkid")', isError: false })
const read = await server.call('harness_read', { name: 'mcpkid' })
expect(read.text).toContain('asked: [from Cursor outside Harness · ')
expect(read.text).toContain('hello from mcp')
diff --git a/cli/src/agentClient/commands.ts b/cli/src/agentClient/commands.ts
index 8a9619dc9..f16fb1b59 100644
--- a/cli/src/agentClient/commands.ts
+++ b/cli/src/agentClient/commands.ts
@@ -59,6 +59,21 @@ It is refused while the harness is working, unless --now. An agent may close onl
export const EXIT = { ok: 0, failed: 1, usage: 2, needsInput: 3, stopped: 4, timeout: 124 } as const
+/** Set by `harness mcp` (mcp.ts) for the verbs it runs: their next steps are then named as its tools. */
+export const VIA_MCP_ENV = 'HARNESS_VIA_MCP'
+const TOOL_OF = { ps: 'harness_list', show: 'harness_read', wait: 'harness_wait', send: 'harness_send', close: 'harness_close' } as const
+
+/**
+ * A next step as the caller can take it: the shell's `harness show x`, or the tool `harness mcp` offers for it. An MCP
+ * client may have no shell at all (Claude Desktop), and its agent was told to run `harness show x` (2026-10-11, in a
+ * clean VM). [option] is a flag and its MCP argument: `--chars 9000` / `chars: 9000`.
+ */
+export function step(env: NodeJS.ProcessEnv, verb: keyof typeof TOOL_OF, name = '', option?: { flag: string; arg: string }): string {
+ if (env[VIA_MCP_ENV] !== '1') return ['harness', verb, name, option?.flag, verb === 'send' ? '"…"' : ''].filter(Boolean).join(' ')
+ const args = [name && `${verb === 'send' ? 'to' : verb === 'wait' ? 'names' : 'name'}: "${name}"`, option?.arg].filter(Boolean)
+ return `${TOOL_OF[verb]}${args.length ? ` (${args.join(', ')})` : ''}`
+}
+
const DEFAULT_CHARS = 4_000
const DEFAULT_TIMEOUT_MS = 30 * 60_000
const DEFAULT_INTERVAL_MS = 3_000
@@ -178,7 +193,7 @@ async function target(s: Setup, o: Opened, name: string): Promise<Target> {
if (!frame) { daemon.close(); throw new AgentClientError('GONE', `${elsewhere[0].name} is no longer on its machine.`) }
return { daemon, frame, machineId: row.child.machineId, machine: row.child.machineId.slice(0, 8), yours: true, remote: true }
}
- throw new AgentClientError('UNKNOWN_HARNESS', `No harness named "${name}" on this machine. \`harness ps\` lists them.`)
+ throw new AgentClientError('UNKNOWN_HARNESS', `No harness named "${name}" on this machine. \`${step(s.env, 'ps')}\` lists them.`)
}
type Screen = 'working' | 'needs-input' | 'idle' | 'draft'
@@ -340,7 +355,7 @@ export function showCommand(argv: readonly string[], deps: ClientDeps = {}): Pro
s.out(`asked: ${clip(result.ask ?? '', 600)}`)
s.out(`answer${result.tools ? ` (after ${result.tools} tool calls)` : ''}:`)
s.out(result.answer || '(no text)')
- if (result.truncated) s.out(`… ${answer.length - chars} more characters: harness show ${result.name} --chars ${answer.length}`)
+ if (result.truncated) s.out(`… ${answer.length - chars} more characters: ${step(s.env, 'show', result.name, { flag: `--chars ${answer.length}`, arg: `chars: ${answer.length}` })}`)
}
if (state === 'needs-input') s.out(`It is waiting for the person (a question or a permission). Only the person answers it.`)
}
@@ -418,9 +433,9 @@ export function waitCommand(argv: readonly string[], deps: ClientDeps = {}): Pro
const results = targets.filter((t) => settled.has(t)).map((t) => ({ name: t.frame.name ?? t.frame.id.slice(0, 8), id: t.frame.id, state: settled.get(t)! }))
if (flags.has('--json')) s.out(JSON.stringify({ harnesses: results }, null, 1))
else for (const r of results) {
- const next = r.state === 'idle' ? `read it: harness show ${r.name}`
+ const next = r.state === 'idle' ? `read it: ${step(s.env, 'show', r.name)}`
: r.state === 'needs-input' ? 'it waits for the person (a question or a permission); only the person answers it'
- : r.state === 'timeout' ? `still working; wait again or read it: harness show ${r.name}`
+ : r.state === 'timeout' ? `still working; wait again or read it: ${step(s.env, 'show', r.name)}`
: r.state === 'stopped' ? 'it was stopped' : 'it is gone'
s.out(`${r.name}: ${r.state} · ${next}`)
}
@@ -455,9 +470,9 @@ export function closeCommand(argv: readonly string[], deps: ClientDeps = {}): Pr
agentId: t.frame.id, sessionId: t.frame.sessionId ?? '', createdAt: t.frame.createdAt ?? '', mode: flags.has('--now') ? 'now' : 'idle',
}, 60_000)
if (reply.error === 'SESSION_NOT_IDLE') {
- throw new AgentClientError('WORKING', `${name} is ${reply.activity === 'needs_input' ? 'waiting for the person' : 'working'}. Wait for it (harness wait ${name}), or close it anyway with --now.`)
+ throw new AgentClientError('WORKING', `${name} is ${reply.activity === 'needs_input' ? 'waiting for the person' : 'working'}. Wait for it (${step(s.env, 'wait', name)}), or close it anyway with ${s.env[VIA_MCP_ENV] === '1' ? 'now: true' : '--now'}.`)
}
- if (reply.error === 'AGENT_CHANGED') throw new AgentClientError('AGENT_CHANGED', `${name} changed while closing. Check it with harness show ${name}, then try again.`)
+ if (reply.error === 'AGENT_CHANGED') throw new AgentClientError('AGENT_CHANGED', `${name} changed while closing. Check it with ${step(s.env, 'show', name)}, then try again.`)
if (reply.error) throw new AgentClientError(String(reply.error), typeof reply.detail === 'string' && reply.detail ? reply.detail : `Could not close ${name}.`)
s.out(flags.has('--json') ? JSON.stringify({ name, id: t.frame.id, closed: true }) : `Closed ${name}. Its conversation is kept.`)
return EXIT.ok
@@ -609,7 +624,7 @@ export async function agentOrigin(deps: ClientDeps = {}, record: Rpc = messagesR
},
next: (agent) => {
const at = addressOf({ machineId: '', agentId: String(agent.id ?? ''), name: String(agent.name ?? ''), engine: '' })
- return `Read it: harness show ${at} · wait for it: harness wait ${at}${caller.outside ? '' : ` · message it: harness send ${at} "…"`}`
+ return `Read it: ${step(s.env, 'show', at)} · wait for it: ${step(s.env, 'wait', at)}${caller.outside ? '' : ` · message it: ${step(s.env, 'send', at)}`}`
},
}
}
diff --git a/cli/src/agentClient/mcp.spec.ts b/cli/src/agentClient/mcp.spec.ts
index a9288dead..ecd94cd79 100644
--- a/cli/src/agentClient/mcp.spec.ts
+++ b/cli/src/agentClient/mcp.spec.ts
@@ -1,4 +1,5 @@
import { PassThrough } from 'node:stream'
+import { step } from './commands.js'
import { describe, expect, it } from 'vitest'
import { agentOfClient, answer, callerEnv, INSTRUCTIONS, mcpCommand, PROTOCOL_VERSIONS, result, type McpDeps, type Ran } from './mcp.js'
@@ -60,13 +61,26 @@ describe('harness mcp', () => {
})
it('says whose session it is when the agent did not, and leaves a harness pane and a named session alone', () => {
- expect(callerEnv(deps({ env: { PATH: '/bin' } }), 'cursor-vscode')).toEqual({ PATH: '/bin', AI_AGENT: 'cursor', HARNESS_AGENT_SESSION: 'mcp-1' })
- expect(callerEnv(deps({ env: { AI_AGENT: 'amp_1_agent' } }))).toEqual({ AI_AGENT: 'amp_1_agent', HARNESS_AGENT_SESSION: 'mcp-1' })
+ const via = { HARNESS_VIA_MCP: '1' }
+ expect(callerEnv(deps({ env: { PATH: '/bin' } }), 'cursor-vscode')).toEqual({ PATH: '/bin', AI_AGENT: 'cursor', HARNESS_AGENT_SESSION: 'mcp-1', ...via })
+ expect(callerEnv(deps({ env: { AI_AGENT: 'amp_1_agent' } }))).toEqual({ AI_AGENT: 'amp_1_agent', HARNESS_AGENT_SESSION: 'mcp-1', ...via })
expect(callerEnv(deps({ env: {} }))).toMatchObject({ AI_AGENT: 'mcp-client' })
expect(callerEnv(deps({ env: {}, session: undefined }))).toMatchObject({ HARNESS_AGENT_SESSION: `mcp-${process.ppid}` })
- expect(callerEnv(deps({ env: { CLAUDECODE: '1', CLAUDE_CODE_SESSION_ID: 's' } }), 'claude-code')).toEqual({ CLAUDECODE: '1', CLAUDE_CODE_SESSION_ID: 's' })
- expect(callerEnv(deps({ env: { CODEX_THREAD_ID: 't' } }))).toEqual({ CODEX_THREAD_ID: 't' })
- expect(callerEnv(deps({ env: { TMUX_PANE: '%1' }, inPane: true }))).toEqual({ TMUX_PANE: '%1' })
+ expect(callerEnv(deps({ env: { CLAUDECODE: '1', CLAUDE_CODE_SESSION_ID: 's' } }), 'claude-code')).toEqual({ CLAUDECODE: '1', CLAUDE_CODE_SESSION_ID: 's', ...via })
+ expect(callerEnv(deps({ env: { CODEX_THREAD_ID: 't' } }))).toEqual({ CODEX_THREAD_ID: 't', ...via })
+ expect(callerEnv(deps({ env: { TMUX_PANE: '%1' }, inPane: true }))).toEqual({ TMUX_PANE: '%1', ...via })
+ })
+
+ it('has the verbs it runs name their next steps as its tools, and the shell keeps its own', () => {
+ const mcp = { HARNESS_VIA_MCP: '1' }
+ expect(step(mcp, 'show', 'reviewer')).toBe('harness_read (name: "reviewer")')
+ expect(step(mcp, 'wait', 'reviewer')).toBe('harness_wait (names: "reviewer")')
+ expect(step(mcp, 'send', 'reviewer')).toBe('harness_send (to: "reviewer")')
+ expect(step(mcp, 'ps')).toBe('harness_list')
+ expect(step(mcp, 'show', 'reviewer', { flag: '--chars 9000', arg: 'chars: 9000' })).toBe('harness_read (name: "reviewer", chars: 9000)')
+ expect(step({}, 'show', 'reviewer', { flag: '--chars 9000', arg: 'chars: 9000' })).toBe('harness show reviewer --chars 9000')
+ expect(step({}, 'send', 'reviewer')).toBe('harness send reviewer "…"')
+ expect(step({}, 'ps')).toBe('harness ps')
})
it('knows the agents MCP clients are by the names they give', () => {
diff --git a/cli/src/agentClient/mcp.ts b/cli/src/agentClient/mcp.ts
index 785a3ac77..eb280beb6 100644
--- a/cli/src/agentClient/mcp.ts
+++ b/cli/src/agentClient/mcp.ts
@@ -15,7 +15,7 @@ import { isAbsolute, resolve } from 'node:path'
import { createInterface } from 'node:readline'
import { VERSION } from '../version.js'
import { AGENT_SESSION_ENV } from './model.js'
-import { EXIT } from './commands.js'
+import { EXIT, VIA_MCP_ENV } from './commands.js'
/** Newest first: the client's own when it is one of these, else the newest. */
export const PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'] as const
@@ -172,7 +172,8 @@ export async function answer(message: Message, deps: McpDeps, state: { client?:
* and Codex's shells do; an MCP server's environment may not). `AI_AGENT` names the agent, as its client said.
*/
export function callerEnv(deps: McpDeps, client = ''): NodeJS.ProcessEnv {
- const env = { ...(deps.env ?? process.env) }
+ // The verbs then name their next steps as this server's tools.
+ const env: NodeJS.ProcessEnv = { ...(deps.env ?? process.env), [VIA_MCP_ENV]: '1' }
if (deps.inPane || (env.CLAUDECODE === '1' && env.CLAUDE_CODE_SESSION_ID) || env.CODEX_THREAD_ID) return env
if (!env.AI_AGENT) env.AI_AGENT = agentOfClient(client)
env[AGENT_SESSION_ENV] = deps.session ?? `mcp-${process.ppid}`