Harnest MCP
Supports Amp via MCP configuration as a lead client and as a downstream coding agent, enabling approved-write handoffs with native-session follow-up on Linux, macOS, or WSL.
Installs an MCP bridge for GitHub Copilot CLI so it can act as a lead client, discover handoff tools, dispatch durable coding tasks to downstream agents, and track their progress and results.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Harnest MCP
Harnest gives an MCP lead client durable handoffs to native coding agents. The lead chooses which downstream agent runs a task, follows its progress, and retrieves a validated receipt. Harnest can also run dependency graphs across agents. The v0.1.0 release is distributed as a tagged source checkout from the private GitHub repository.
Quick start
Use Git with authenticated access to the private repository, Bun, and Node.js 22.19 or newer for the default install with optional Taskflow packages. Install and authenticate each downstream CLI through its native setup.
From a shell with the downstream CLIs on PATH, clone to a directory you can keep in place. This example configures Codex as the lead client and installs the shared daemon.
git clone https://github.com/harshanandak/harnest.git
cd harnest
bun install --frozen-lockfile
bun run setup codex
bun run doctor --host codexRestart Codex and confirm it discovers handoff_workflow, handoff_status, handoff_trace, and handoff_result. Then try your first handoff.
Run bun run setup --help for lead host names. Setup can install the MCP bridge for GitHub Copilot CLI, Qwen Code, Kilo, Cline CLI, Kiro CLI, Factory Droid, Auggie, Kimi CLI, and Devin CLI. For Goose and Mistral Vibe, setup prints manual MCP configuration. These preset setups have CI fixture coverage only, with no live CLI testing. See the preset lead host instructions.
Use bun run setup <host> for claude, codex, opencode, cursor, pi, gemini, and amp as well. For Cursor, add --project "/absolute/path/to/project" to install its workspace files. bun run setup other prints a stdio bridge snippet for other clients. See the HTTP setup and verification instructions.
Run bun run setup remove <host> to disconnect Harnest from an automatic ACP preset, Gemini CLI, Amp, or Cursor's user config. Use the same config path overrides as setup. The command backs up the file before removing the Harnest MCP entry. See the host removal instructions.
Related MCP server: Navish Commander
Supported clients and downstream agents
A lead client connects to Harnest through MCP. The downstream agent executes the task and uses its own native authentication. Direct MCP use requires only the connection and downstream CLI.
Agent or client | Lead connection | Downstream target and limits |
Claude Code | Daemon HTTP via the plugin's header helper |
|
Codex | Stdio bridge via the host installer |
|
OpenCode | Daemon HTTP via the integration installer |
|
Pi | Daemon HTTP via the extension |
|
Cursor | Stdio bridge via the integration installer |
|
Gemini CLI | MCP configuration |
|
Amp | MCP configuration |
|
Registered ACP agent | Depends on the client's MCP support |
|
Gemini, Amp, and generic ACP use native-session follow-up and reject session transport and live controls. See supported agents for the full control and platform boundaries.
Choose a connection
Shared daemon HTTP. Use
http://127.0.0.1:41237/mcpwith the daemon's local bearer credential. The HTTP setup instructions show how to write the header directly into a private client config. URL-only clients need a running daemon. Usebun run daemon startfor manual startup.Stdio bridge. Configure
node /absolute/path/to/harnest/src/mcp-bridge.mjsfor clients that require stdio. The bridge starts the daemon on demand and forwards requests to it.Standalone stdio. Configure
node /absolute/path/to/harnest/src/mcp-server.mjsto give each invocation its own runtime.
Host installers register a login item by default using Windows Task Scheduler, a macOS LaunchAgent, or a systemd user unit. Run the installer with the intended HARNEST_STATE_DIR if customized and the downstream CLIs on PATH. The login item captures PATH, the resolved job and daemon directories, and supported non-secret Harnest runtime settings. Pass --no-autostart to skip login registration. The daemon uses its startup environment and machine-local configuration. See daemon lifecycle and host setup and restore.
Your first handoff
With Codex installed and authenticated downstream, call handoff_workflow with this input. Replace cwd with the absolute path to a Git checkout.
{
"request": {
"requestId": "first-read-001",
"target": "codex",
"task": "Summarize how tests are organized in this repository. Include file paths.",
"cwd": "/absolute/path/to/project",
"route": { "model": "gpt-6.1-terra", "thinking": "high" },
"metadata": { "routing": { "modelVersion": "pin" } },
"execution": { "background": true },
"policy": { "write": false }
}
}Use the returned jobId with handoff_status. Call handoff_trace with that ID and pass the previous response's nextSequence as afterSequence to fetch only new progress. After the job settles, fetch the route, session identity, and final text with handoff_result. To cancel, call handoff_cancel with { "jobId": "<returned job ID>" } and poll status for acknowledgement. See tool inputs and examples.
Workflows and graphs
Use a single background handoff for a bounded task you want to recover by job or request ID.
Use a dependency graph for parallel reviews followed by synthesis. Each node receives results only from its direct dependencies. A retry preserves completed nodes. See the graph contract.
Use a JavaScript workflow for loops, branches, or fan-out decided at runtime.
Routing and model defaults
For new Codex leaf routes, use gpt-6.2-sol for code writing, gpt-6.1-sol for reviews and investigations, and gpt-6.1-terra for read-only non-code research, lookups, and audits. All three use high reasoning. The native Codex worker bridges also use Terra at high effort to forward requests. Their downstream routes are chosen independently.
Explicit model and effort pins take precedence. Set metadata.routing.modelVersion to pin to keep the selected version. For other provider routes, check the native catalog and select a model that provider exposes. Use handoff_routing_preview to inspect the selected route and its catalog freshness before dispatch. An omitted model can leave the choice to the downstream client's configuration. See routing preferences and precedence.
Safety, data, and limits
Approve write scope before dispatch. Generic ACP trust allows the registered executable to load native configuration and extensions. Requests, task context, traces, receipts, and downstream output can be stored locally as plaintext. Keep credentials out of handoffs and protect the state directory.
The daemon binds to loopback. Its private
tokenfile lives under%LOCALAPPDATA%/harnest/daemon/on Windows,~/Library/Application Support/harnest/daemon/on macOS, and$XDG_STATE_HOME/harnest/daemon/on Linux (default~/.local/state/harnest/daemon/). WithHARNEST_STATE_DIRset,daemon/is a sibling of the jobs directory. Host settings and installer backups may contain the local credential. Keep them private.CI host-installation fixtures cover configuration and reversal. Live host installation and authenticated downstream coverage vary. See the release limits for the verification boundary, unsupported controls, and platform constraints.
Update or remove
For an update, fetch tags, check out the desired release tag, run bun install --frozen-lockfile, rerun the integration installer, and restart the host. Keep the installer backups. To roll back, repeat with the previous tag, or follow the host restore instructions for configuration changes.
To remove the daemon login item, run these commands from the checkout with the same state settings used at install. If stop reports busy, wait for active work to finish and run stop again before removing autostart.
bun run daemon stop
bun run daemon uninstall-autostartRun uninstall as the installing user. On Linux, use the same XDG_CONFIG_HOME if you customized it. This preserves durable jobs and host configurations. To disconnect a host, remove its Harnest MCP entry or restore its installer backup, then restart it.
Documentation index
Routing preferences, live transcript behavior, and registered ACP agents
Architecture and the adapter contract
Development and releases
GitHub CI runs the Node test suite through bun run check, then runs bun run smoke:mcp, bun run validate:plugin, and the memory gates. When editing worker definitions, update scripts/build-workers.mjs and regenerate the checked-in files with node scripts/build-workers.mjs.
See the changelog and release process for the private GitHub source releases.
Support, security, and license
Report installation and usage problems in GitHub Issues with the tag, host, downstream CLI, OS, and sanitized reproduction details. Follow the security policy for sensitive reports. Harnest is licensed under the MIT License.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Public MCP for agent verification, work discovery and governed interoperability.
Workflow diagnostics, capability routing, and x402 settlement for MCP-compatible agents.
- aXDeprecatedio.github.ax-platform
Agent-native collaboration network: orchestrate a team of long-running agents from any MCP client.
Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables agents to submit and manage persistent, dependency-aware task graphs with immutable artifacts, resource reservations, durable event streaming, and retryable process execution over MCP.12MIT
- AlicenseNot gradedqualityBmaintenanceEnables running authorized file operations, persistent processes, and parallel batches from an MCP client, with durable receipts and artifact verification, and allows reconnecting to collect workers without restarting them.MIT
- AlicenseNot gradedqualityCmaintenanceEnables coding assistants to create versioned work contracts, claim tasks with durable leases, record checkpoints and decisions, and hand off unfinished work to another supported agent. Provides independently observed verification receipts and cross-agent continuity through a local-first MCP STDIO server.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceLets agent lanes and their supervising human share one protocol-governed, local-first queue where requests, questions, handoffs, approvals, and verifications are logged as typed items with immutable history and evidence refs to commits, tags, runs, and artifacts. Exposes this over stdio or Streamable HTTP so MCP clients can file, acknowledge, transition, and verify work while the daemon and SQLite event log stay on the user's machine.Apache 2.0