{"record":{"id":"be4e09a163c35740","repo":"headroomlabs-ai/headroom","slug":"no-agents-matched-the-requested-filter","errorCode":null,"errorMessage":"No agents matched the requested filter.","messagePattern":"No agents matched the requested filter\\.","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"warning","filePath":"headroom/cli/mcp.py","lineNumber":169,"sourceCode":"    \"\"\"\n    try:\n        import mcp  # noqa: F401\n    except ImportError:\n        click.echo(\"Error: MCP SDK not installed.\", err=True)\n        click.echo(\"Install with: pip install 'headroom-ai[mcp]'\", err=True)\n        raise SystemExit(1) from None\n\n    from headroom.mcp_registry import any_succeeded, format_results, install_everywhere\n\n    results = install_everywhere(\n        proxy_url=proxy_url,\n        agents=list(agents) if agents else None,\n        force=force,\n    )\n\n    if not results:\n        click.echo(\"No agents matched the requested filter.\")\n        raise SystemExit(1)\n\n    click.echo(\"Installing Headroom MCP server...\")\n    for line in format_results(\n        results,\n        verbose=True,\n        overwrite_hint=f\"headroom mcp install --proxy-url {proxy_url} --force\",\n    ):\n        click.echo(line)\n\n    if not any_succeeded(results):\n        raise SystemExit(1)\n\n    click.echo(\n        f\"\\nNext steps:\\n\"\n        f\"  1. Start the Headroom proxy (if not running): headroom proxy\\n\"\n        f\"  2. Start your agent (e.g.) ANTHROPIC_BASE_URL={proxy_url} claude\\n\"\n        f\"  3. Restart any agent that was already running so it picks up the new MCP server.\\n\"\n    )","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/cli/mcp.py#L151-L187","documentation":"`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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run without --agent to see which agents auto-detection finds; if none, install/launch the agent once so its config dir exists","Check the exact agent ids the registry supports (see headroom/mcp_registry.py agent list) and use one verbatim","Ensure HOME is set correctly (su/containers with wrong HOME hide agent configs)","Use --proxy-url/--force as needed once a target agent actually matches"],"exampleFix":"# before\n$ headroom mcp install --agent codex-cli\n# No agents matched the requested filter.\n\n# after\n$ headroom mcp install --agent codex","handlingStrategy":"validation","validationCode":"from headroom.mcp_registry import detect_agents  # or equivalent discovery helper\ntargets = detect_agents(agents=agent_filter)\nif not targets:\n    raise SystemExit(\"no supported agent configs found — install the agent first or fix --agent\")","typeGuard":"def agent_matches(registry_agents: list[str], requested: str | None) -> bool:\n    if requested is None:\n        return len(registry_agents) > 0\n    return requested in registry_agents","tryCatchPattern":"proc = subprocess.run([\"headroom\", \"mcp\", \"install\", ...], capture_output=True, text=True)\nif proc.returncode == 1 and \"No agents matched\" in proc.stdout:\n    print(\"agent filter matched nothing — check agent id / install an agent\")","preventionTips":["Use exact agent ids from headroom's registry (see mcp_registry.py), not vendor marketing names","Provision the agent (run it once) before scripting headroom mcp install","In containers, set HOME correctly so agent config directories are discoverable"],"tags":["cli","mcp","agent-detection","filter","system-exit"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}