agent-harnesses-mcp

agent-harnesses MCP server

mcp-name: io.github.RyanAlberts/agent-harnesses

The best-of-Agent-Harnesses list as an MCP server, so agents can recommend harnesses instead of you reading 100+ table rows.

Single file, stdio transport, no clone needed — it fetches harnesses.json from this repo at startup (or reads it locally from a checkout). Requires uv.

Install

Published on PyPI and the official MCP registry as io.github.RyanAlberts/agent-harnesses. Claude Code:

claude mcp add agent-harnesses -- uvx agent-harnesses-mcp

Any other MCP client (Cursor, Codex, Gemini CLI, ...):

{
  "mcpServers": {
    "agent-harnesses": {
      "command": "uvx",
      "args": ["agent-harnesses-mcp"]
    }
  }
}

No-install alternative — run the single source file straight from this repo:

claude mcp add agent-harnesses -- uv run https://raw.githubusercontent.com/RyanAlberts/best-of-Agent-Harnesses/main/mcp/server.py

Tools

Tool	What it does
recommend(need, language?, must_run_unattended?, open_source_only?)	Opinionated single recommendation — a decision, not a list. Returns one top pick with the reason, up to two alternatives, any harnesses to avoid for this need (archived, or flagged for star manipulation — with why), and the most relevant decision guide to read next.
pick_harness(use_case, max_complexity?, min_autonomy?, min_recovery?, open_source_only?, limit?)	Ranked recommendations for a use case, seeded by the list's hand-curated use-case index. max_complexity caps adoption surface (super simple → complex); min_autonomy requires a designed autonomy regime (step-gated → headless); min_recovery requires a failure-recovery tier (none → durable).
compare(github_ids)	Side-by-side of 2–4 harnesses — "should I use X or Y?". Records aligned on the list's axes — including the researched deep-dive axes (sandboxing, context memory, lifecycle hooks, prompt optimization, build-vs-buy tier) — an edge summary naming who leads where, a warning when a requested repo is in the graveyard (archived or integrity-flagged), and the decision guide covering the matchup when one exists.
compare_for(use_case, limit?, open_source_only?)	Task-based comparison — "compare the best options for X" in one call. Ranks candidates like pick_harness, takes the top 2–4, and returns the full side-by-side with each pick's ranking reason.
search_harnesses(query, limit?)	Keyword search across names, descriptions, tags, and categories.
get_harness(github_id)	Full record for one project.
list_comparisons()	The head-to-head decision guides (OpenClaw vs Hermes, terminal coding agents, …) with summaries.
get_comparison(slug)	Full markdown of one guide — architecture trade-offs, field reports, billing reality. Always current: served from the repo's main.
list_categories()	The 10 categories, use-case intents, and the complexity/autonomy/recovery scales.

Example: "recommend('an always-on personal assistant that lives in my chat apps', open_source_only=True)" → one top pick with the reason, two alternatives, anything to avoid for this need, and the guide to read next.

Example: "compare(['openclaw/openclaw', 'NousResearch/hermes-agent'])" → both records side by side, who leads on which axis, and a pointer to the OpenClaw vs Hermes guide.

Example: "pick_harness('sandboxed code execution for generated code', max_complexity='slightly complex', open_source_only=True)" → E2B, smolagents, Daytona... each with stars, tier, license signal, and a one-line reason.

Data is regenerated by scripts/generate.py; star counts carry a stars_captured date, and the comparisons index is rebuilt from comparisons/*.md on every refresh — the server always serves current main.

Distribution

The server is packaged as agent-harnesses-mcp (this directory's pyproject.toml) and live in the official MCP registry as io.github.RyanAlberts/agent-harnesses (server.json at the repo root), which directories like Glama and PulseMCP crawl. The registry validates PyPI ownership via the mcp-name: marker at the top of this README — keep it.

Publishing (maintainer runbook)

Releases are automated by .github/workflows/publish-mcp.yml on a mcp-v* tag: it builds the wheel, publishes to PyPI via trusted publishing, and publishes server.json to the official MCP registry via GitHub OIDC.

One-time setup, then never again:

• On pypi.org: create the project name agent-harnesses-mcp → Settings → Publishing → add a trusted publisher: owner RyanAlberts, repo best-of-Agent-Harnesses, workflow publish-mcp.yml. No API tokens.
• Nothing for the MCP registry — GitHub OIDC from this repo authorizes the io.github.RyanAlberts/* namespace automatically.

Per release: bump the version in mcp/pyproject.toml and server.json (the workflow fails loudly on mismatch), then git tag mcp-v<version> && git push origin mcp-v<version>.

Directories like Glama, PulseMCP, and mcpservers.org crawl the official registry — no per-directory submissions needed. (Smithery's current publish flow takes hosted-HTTP servers or .mcpb bundles, not stdio-from-GitHub, so this server isn't listed there by design.)