headroomlabs-ai/headroom · warning · SystemExit

No agents matched the requested filter.

Error message

No agents matched the requested filter.

What it means

`headroom mcp install` filters known coding agents (Claude Code, Codex, Cursor, etc.) via install_everywhere(agents=...). If the filter matches zero agents — either because --agent named an unknown id or because no supported agent is installed/detected — results is empty, the message 'No agents matched the requested filter.' is printed, and the CLI exits 1. Note this is a distinct, later exit than the ImportError guard: dependencies were fine, but there was nothing to install into.

Source

Thrown at headroom/cli/mcp.py:169

    """
    try:
        import mcp  # noqa: F401
    except ImportError:
        click.echo("Error: MCP SDK not installed.", err=True)
        click.echo("Install with: pip install 'headroom-ai[mcp]'", err=True)
        raise SystemExit(1) from None

    from headroom.mcp_registry import any_succeeded, format_results, install_everywhere

    results = install_everywhere(
        proxy_url=proxy_url,
        agents=list(agents) if agents else None,
        force=force,
    )

    if not results:
        click.echo("No agents matched the requested filter.")
        raise SystemExit(1)

    click.echo("Installing Headroom MCP server...")
    for line in format_results(
        results,
        verbose=True,
        overwrite_hint=f"headroom mcp install --proxy-url {proxy_url} --force",
    ):
        click.echo(line)

    if not any_succeeded(results):
        raise SystemExit(1)

    click.echo(
        f"\nNext steps:\n"
        f"  1. Start the Headroom proxy (if not running): headroom proxy\n"
        f"  2. Start your agent (e.g.) ANTHROPIC_BASE_URL={proxy_url} claude\n"
        f"  3. Restart any agent that was already running so it picks up the new MCP server.\n"
    )

View on GitHub (pinned to 322425c43b)

Solutions

  1. Run without --agent to see which agents auto-detection finds; if none, install/launch the agent once so its config dir exists
  2. Check the exact agent ids the registry supports (see headroom/mcp_registry.py agent list) and use one verbatim
  3. Ensure HOME is set correctly (su/containers with wrong HOME hide agent configs)
  4. Use --proxy-url/--force as needed once a target agent actually matches

Example fix

# before
$ headroom mcp install --agent codex-cli
# No agents matched the requested filter.

# after
$ headroom mcp install --agent codex
Defensive patterns

Strategy: validation

Validate before calling

from headroom.mcp_registry import detect_agents  # or equivalent discovery helper
targets = detect_agents(agents=agent_filter)
if not targets:
    raise SystemExit("no supported agent configs found — install the agent first or fix --agent")

Type guard

def agent_matches(registry_agents: list[str], requested: str | None) -> bool:
    if requested is None:
        return len(registry_agents) > 0
    return requested in registry_agents

Try / catch

proc = subprocess.run(["headroom", "mcp", "install", ...], capture_output=True, text=True)
if proc.returncode == 1 and "No agents matched" in proc.stdout:
    print("agent filter matched nothing — check agent id / install an agent")

Prevention

When it happens

Trigger: Running `headroom mcp install --agent <name>` where <name> is not one of the supported agent ids, or omitting --agent on a machine where none of the supported agents have config directories.

Common situations: Typo'd agent names (--agent codex-cli vs codex); running on a fresh machine/CI container before any agent is installed; agents installed in non-default HOME/XDG locations the detector does not scan.

Related errors

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/be4e09a163c35740. Report an issue: GitHub.