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.

@autonomous-ai/harness-mcp: harness mcp for clients that install from npm (#1189)

Deee36ed96a19fa
diff --git a/cli/RELEASE.md b/cli/RELEASE.md
index 2ee5b1486..6213dc778 100644
--- a/cli/RELEASE.md
+++ b/cli/RELEASE.md
@@ -79,6 +79,20 @@ Its command contract (flags, exit codes, what it refuses) is pinned by `cli/src/
which runs with the rest of `make cli-test`. Not to be confused with `cli/scripts/install-cli.sh`, the
local dev loop below.
+## The npm wrapper of `harness mcp`
+
+`cli/packages/harness-mcp` is `@autonomous-ai/harness-mcp`, for MCP clients and directories that install servers
+with `npx`. It is not the CLI: it runs `harness mcp` from the installed CLI, and where there is none it offers one
+tool that says how to install it. Its `mcpName` ties it to the Official MCP Registry entry. It changes rarely, and
+apart from the CLI's releases:
+
+```bash
+npm login # an account in the npm organization autonomous-ai
+cd cli/packages/harness-mcp && npm publish --access public
+```
+
+Its tests are `cli/src/agentClient/mcpPackage.spec.ts`, in `make cli-test`.
+
## Local install (no upload)
`bash cli/scripts/install-cli.sh` bundles **this working tree** into `~/.harness/cli` — the same
diff --git a/cli/packages/harness-mcp/README.md b/cli/packages/harness-mcp/README.md
new file mode 100644
index 000000000..7aef0ae28
--- /dev/null
+++ b/cli/packages/harness-mcp/README.md
@@ -0,0 +1,44 @@
+# @autonomous-ai/harness-mcp
+
+[Harness](https://harness.autonomous.ai/agents) as an MCP server, for clients that install servers from npm.
+
+Harness runs coding agents (Claude Code, Codex) in sessions of their own, on this computer or the person's other
+machines, and the person can watch and join every one in the Harness app. With this server an agent can start
+harnesses, wait for them, read their answers and close them:
+
+| Tool | What it does |
+|---|---|
+| `harness_list` | the harnesses here: state, who started each, what each is about |
+| `harness_start` | start an agent on a task in a folder, by name |
+| `harness_wait` | wait until harnesses stop working |
+| `harness_read` | a harness's last ask and its answer |
+| `harness_close` | close a harness you started |
+
+An agent may give work to, and close, only the harnesses it started.
+
+## Install
+
+Harness itself (macOS or Linux; no account needed for harnesses on this computer):
+
+```
+curl -fsSL https://harness.autonomous.ai/cli/install.sh | bash
+harness start
+```
+
+Then add the server to your client, for example:
+
+```
+claude mcp add harness -- npx -y @autonomous-ai/harness-mcp
+```
+
+```json
+{ "mcpServers": { "harness": { "command": "npx", "args": ["-y", "@autonomous-ai/harness-mcp"] } } }
+```
+
+This package runs `harness mcp` from the installed CLI (or `HARNESS_BIN`). Where Harness is not installed, the
+server offers one tool, `harness_setup`, that says how to install it.
+
+Claude Code and Codex can also install the Harness plugin, which brings a skill with it: see
+[harness.autonomous.ai/agents](https://harness.autonomous.ai/agents).
+
+MIT licensed. Source: [autonomous-ai/openharness](https://github.com/autonomous-ai/openharness/tree/main/cli/packages/harness-mcp).
diff --git a/cli/packages/harness-mcp/bin.mjs b/cli/packages/harness-mcp/bin.mjs
new file mode 100755
index 000000000..5c586eea0
--- /dev/null
+++ b/cli/packages/harness-mcp/bin.mjs
@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { findHarness, runHarness, serveSetup } from './index.mjs'
+
+const harness = findHarness()
+if (harness) process.exitCode = await runHarness(harness)
+else await serveSetup()
diff --git a/cli/packages/harness-mcp/index.mjs b/cli/packages/harness-mcp/index.mjs
new file mode 100644
index 000000000..a87ad45c6
--- /dev/null
+++ b/cli/packages/harness-mcp/index.mjs
@@ -0,0 +1,97 @@
+/**
+ * `npx -y @autonomous-ai/harness-mcp`: Harness's MCP server for clients that install servers from npm. Harness is
+ * not an npm package (its installer brings its own Node and tmux, cli/scripts/install.sh), so this finds the
+ * `harness` command and runs `harness mcp` in its place. Where Harness is not installed it still answers, with one
+ * tool that says how to install it: an agent that found Harness in a directory can then ask its person to.
+ *
+ * No dependencies: it runs before anything is installed.
+ */
+import { spawn } from 'node:child_process'
+import { accessSync, constants } from 'node:fs'
+import { homedir } from 'node:os'
+import { delimiter, join } from 'node:path'
+import { createInterface } from 'node:readline'
+
+export const INSTALL = 'curl -fsSL https://harness.autonomous.ai/cli/install.sh | bash'
+
+/** Where `harness` is: HARNESS_BIN, else the PATH, else where the installer links it (a client may start this with
+ * a PATH that leaves out ~/.local/bin). */
+export function findHarness(env = process.env, home = homedir(), executable = isExecutable) {
+ const candidates = [
+ env.HARNESS_BIN,
+ ...(env.PATH ?? '').split(delimiter).filter(Boolean).map((dir) => join(dir, 'harness')),
+ join(home, '.local', 'bin', 'harness'),
+ ].filter(Boolean)
+ return candidates.find((path) => executable(path)) ?? null
+}
+
+function isExecutable(path) {
+ try { accessSync(path, constants.X_OK); return true } catch { return false }
+}
+
+const SETUP_TEXT = (platform) => platform === 'win32'
+ ? 'Harness runs on macOS and Linux. On Windows, install it inside WSL, and run this server from there.'
+ : [
+ 'Harness is not installed on this computer. It runs coding agents (Claude Code, Codex) in sessions of their own that the person can watch, and gives you tools to start, wait for, read and close them.',
+ '',
+ 'To install it, ask the person, then run:',
+ ` ${INSTALL}`,
+ ' harness start',
+ '',
+ 'No account is needed for harnesses on this computer. Then restart this MCP server (or your client) to get the Harness tools.',
+ 'More: https://harness.autonomous.ai/agents',
+ ].join('\n')
+
+/** The answer to one JSON-RPC message while Harness is not installed, or null for a notification. */
+export function setupAnswer(message, platform = process.platform) {
+ const id = message?.id
+ const isRequest = id !== undefined && id !== null
+ const reply = (result) => ({ jsonrpc: '2.0', id, result })
+ switch (message?.method) {
+ case 'initialize':
+ return reply({
+ protocolVersion: typeof message.params?.protocolVersion === 'string' ? message.params.protocolVersion : '2025-06-18',
+ capabilities: { tools: {} },
+ serverInfo: { name: 'harness', title: 'Harness (not installed)', version: '0.1.0' },
+ instructions: SETUP_TEXT(platform),
+ })
+ case 'ping': return reply({})
+ case 'tools/list':
+ return reply({ tools: [{
+ name: 'harness_setup',
+ description: 'Harness is not installed here. Call this for how to install it, which gives you tools to start, wait for, read and close other coding agents.',
+ inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+ annotations: { readOnlyHint: true },
+ }] })
+ case 'tools/call':
+ if (message.params?.name !== 'harness_setup') return { jsonrpc: '2.0', id, error: { code: -32602, message: `Unknown tool: ${String(message.params?.name)}` } }
+ return reply({ content: [{ type: 'text', text: SETUP_TEXT(platform) }] })
+ default:
+ return isRequest ? { jsonrpc: '2.0', id, error: { code: -32601, message: `Method not found: ${String(message?.method)}` } } : null
+ }
+}
+
+/** Serve [setupAnswer] on newline-delimited JSON-RPC until the input ends. */
+export async function serveSetup(input = process.stdin, output = process.stdout, platform = process.platform) {
+ for await (const line of createInterface({ input, crlfDelay: Infinity })) {
+ if (!line.trim()) continue
+ let message
+ try { message = JSON.parse(line) } catch {
+ output.write(`${JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } })}\n`)
+ continue
+ }
+ const reply = setupAnswer(message, platform)
+ if (reply) output.write(`${JSON.stringify(reply)}\n`)
+ }
+}
+
+/** Run `harness mcp` in this process's place: its stdio, its exit, and the signals a client stops it with. */
+export function runHarness(path, run = spawn) {
+ return new Promise((done) => {
+ const child = run(path, ['mcp'], { stdio: 'inherit' })
+ const forward = (signal) => () => child.kill(signal)
+ for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(signal, forward(signal))
+ child.on('error', () => done(1))
+ child.on('exit', (code, signal) => done(code ?? (signal ? 1 : 0)))
+ })
+}
diff --git a/cli/packages/harness-mcp/package.json b/cli/packages/harness-mcp/package.json
new file mode 100644
index 000000000..fe9981f0c
--- /dev/null
+++ b/cli/packages/harness-mcp/package.json
@@ -0,0 +1,27 @@
+{
+ "name": "@autonomous-ai/harness-mcp",
+ "version": "0.1.0",
+ "description": "Harness as an MCP server: start, wait for, read and close Claude Code and Codex agents the person can watch.",
+ "mcpName": "io.github.autonomous-ai/harness",
+ "type": "module",
+ "bin": {
+ "harness-mcp": "bin.mjs"
+ },
+ "exports": "./index.mjs",
+ "files": [
+ "bin.mjs",
+ "index.mjs",
+ "README.md"
+ ],
+ "engines": {
+ "node": ">=18"
+ },
+ "keywords": ["mcp", "mcp-server", "agents", "claude-code", "codex", "parallel", "harness"],
+ "homepage": "https://harness.autonomous.ai/agents",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/autonomous-ai/openharness.git",
+ "directory": "cli/packages/harness-mcp"
+ },
+ "license": "MIT"
+}
diff --git a/cli/src/agentClient/mcpPackage.spec.ts b/cli/src/agentClient/mcpPackage.spec.ts
new file mode 100644
index 000000000..85d36b388
--- /dev/null
+++ b/cli/src/agentClient/mcpPackage.spec.ts
@@ -0,0 +1,88 @@
+/**
+ * The npm wrapper of `harness mcp` (packages/harness-mcp): plain JavaScript with no dependencies, since it runs
+ * before anything is installed, so it is imported here by path.
+ */
+import { EventEmitter } from 'node:events'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { PassThrough } from 'node:stream'
+import { afterEach, describe, expect, it } from 'vitest'
+
+interface Package {
+ INSTALL: string
+ findHarness(env: Record<string, string | undefined>, home: string, executable?: (path: string) => boolean): string | null
+ setupAnswer(message: unknown, platform?: string): Record<string, any> | null
+ serveSetup(input: NodeJS.ReadableStream, output: NodeJS.WritableStream, platform?: string): Promise<void>
+ runHarness(path: string, run: (path: string, args: string[], options: object) => EventEmitter & { kill(signal: string): void }): Promise<number>
+}
+const where = '../../packages/harness-mcp/index.mjs'
+const pkg = await import(where) as Package
+
+const dirs: string[] = []
+afterEach(() => { for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true }) })
+
+describe('npx @autonomous-ai/harness-mcp', () => {
+ it('finds harness from HARNESS_BIN, the PATH, or where the installer links it', () => {
+ const home = mkdtempSync(join(tmpdir(), 'harness-mcp-'))
+ dirs.push(home)
+ const on = (paths: string[]) => (path: string) => paths.includes(path)
+ expect(pkg.findHarness({ HARNESS_BIN: '/opt/h', PATH: '/usr/bin' }, home, on(['/opt/h', '/usr/bin/harness']))).toBe('/opt/h')
+ expect(pkg.findHarness({ PATH: '/a:/usr/bin' }, home, on(['/usr/bin/harness']))).toBe('/usr/bin/harness')
+ // A client may start it with a PATH that leaves out ~/.local/bin.
+ expect(pkg.findHarness({ PATH: '/usr/bin' }, home, on([join(home, '.local', 'bin', 'harness')]))).toBe(join(home, '.local', 'bin', 'harness'))
+ expect(pkg.findHarness({}, home, on([]))).toBeNull()
+ // The real check: an executable file.
+ const bin = join(home, 'harness')
+ writeFileSync(bin, '#!/bin/sh\n', { mode: 0o755 })
+ expect(pkg.findHarness({ PATH: home }, '/nowhere')).toBe(bin)
+ writeFileSync(join(home, 'plain'), '')
+ expect(pkg.findHarness({ HARNESS_BIN: join(home, 'plain') }, '/nowhere')).toBeNull()
+ })
+
+ it('without Harness, offers one tool that says how to install it', () => {
+ const hello = pkg.setupAnswer({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-03-26' } })!
+ expect(hello.result).toMatchObject({ protocolVersion: '2025-03-26', capabilities: { tools: {} }, serverInfo: { name: 'harness' } })
+ expect(hello.result.instructions).toContain(pkg.INSTALL)
+ expect(pkg.setupAnswer({ jsonrpc: '2.0', id: 2, method: 'initialize' })!.result.protocolVersion).toBe('2025-06-18')
+ expect(pkg.setupAnswer({ jsonrpc: '2.0', id: 3, method: 'tools/list' })!.result.tools.map((t: { name: string }) => t.name)).toEqual(['harness_setup'])
+ const told = pkg.setupAnswer({ jsonrpc: '2.0', id: 4, method: 'tools/call', params: { name: 'harness_setup' } })!
+ expect(told.result.content[0].text).toContain(` ${pkg.INSTALL}\n harness start`)
+ expect(told.result.content[0].text).toContain('ask the person')
+ expect(pkg.setupAnswer({ jsonrpc: '2.0', id: 5, method: 'tools/call', params: { name: 'harness_setup' } }, 'win32')!.result.content[0].text).toContain('WSL')
+ expect(pkg.setupAnswer({ jsonrpc: '2.0', id: 6, method: 'tools/call', params: { name: 'harness_list' } })).toMatchObject({ error: { code: -32602 } })
+ expect(pkg.setupAnswer({ jsonrpc: '2.0', id: 7, method: 'ping' })).toEqual({ jsonrpc: '2.0', id: 7, result: {} })
+ expect(pkg.setupAnswer({ jsonrpc: '2.0', id: 8, method: 'resources/list' })).toMatchObject({ error: { code: -32601 } })
+ expect(pkg.setupAnswer({ jsonrpc: '2.0', method: 'notifications/initialized' })).toBeNull()
+ })
+
+ it('serves that over newline-delimited JSON-RPC', async () => {
+ const input = new PassThrough(), output = new PassThrough()
+ const lines: string[] = []
+ output.on('data', (chunk) => lines.push(...String(chunk).split('\n').filter(Boolean)))
+ const served = pkg.serveSetup(input, output, 'darwin')
+ input.end(`${JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' })}\n\nnope\n${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' })}\n`)
+ await served
+ expect(lines.map((line) => JSON.parse(line))).toEqual([
+ { jsonrpc: '2.0', id: 1, result: { tools: [expect.objectContaining({ name: 'harness_setup' })] } },
+ { jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } },
+ ])
+ })
+
+ it('runs harness mcp in its place, with its exit', async () => {
+ const asked: Array<[string, string[], object]> = []
+ const child = Object.assign(new EventEmitter(), { kill: () => {} })
+ const exited = pkg.runHarness('/bin/harness', (path, args, options) => { asked.push([path, args, options]); return child })
+ child.emit('exit', 3, null)
+ expect(await exited).toBe(3)
+ expect(asked).toEqual([['/bin/harness', ['mcp'], { stdio: 'inherit' }]])
+ const killed = Object.assign(new EventEmitter(), { kill: () => {} })
+ const byStop = pkg.runHarness('/bin/harness', () => killed)
+ killed.emit('exit', null, 'SIGTERM')
+ expect(await byStop).toBe(1)
+ const broken = Object.assign(new EventEmitter(), { kill: () => {} })
+ const failed = pkg.runHarness('/bin/harness', () => broken)
+ broken.emit('error', new Error('ENOENT'))
+ expect(await failed).toBe(1)
+ })
+})