# NousResearch/hermes-agent · MCP SDK missing causes unclear NameError at runtime

## Open now

- 1 issue, 2 PRs open on GitHub.
- #31005: Homebrew bottle 2026.5.16 missing 'mcp' and 'websockets' packages — MCP and browser tools fail at runtime
- PR #34223: fix(mcp): fail fast when sdk is missing
- PR #105586: fix(mcp): fail fast with actionable error when mcp SDK missing (salvage of #34245)

Multiple issues and fixes address a problem where missing MCP or related SDK packages produce confusing NameError exceptions instead of clear ImportError messages. The fixes aim to provide actionable error messages when the MCP SDK is not installed.

## TL;DR

- 8 member(s): 1 open issue(s), 2 closed issue(s), 2 open PR(s), 1 merged PR(s), 2 PR(s) closed without merging.
- A fix was merged to main in PR #31450. Verify it addresses your case.
- **Recommended:** read PR #31450 (and any competing PRs below) before filing. Confirm the merged change covers your symptom.

## Maintainer resolution verdict

- Internal-tracker verdict over this cluster's issue members: `partially_resolved` · deciding PR(s): `pr-31450`. This is distinct from the fix status above. Weigh it yourself.

## How this cluster was grouped

- Link evidence (`STRUCTURAL_PARTIAL`): some members are connected by structural evidence (shared changed files, or a closing/superseded reference); the rest are joined by an automated relevance judgement over their text.
- Members outside that structural core may belong to a different underlying problem.
- Pairwise link density `0.20`: the share of member pairs that carry a link, counting a structural link in full and a relevance-only link at 0.36. `1.00` means every pair is linked.

## Open related issues

- #31005: Homebrew bottle 2026.5.16 missing 'mcp' and 'websockets' packages — MCP and browser tools fail at runtime

## Closed / duplicate issues

- #30904: MCP stdio client raises NameError: name 'StdioServerParameters' is not defined (v0.14.0)
- #34220: mcp add / mcp test raise NameError when mcp package not installed

## Prior & competing PRs

- **#31450: fix(mcp): raise ImportError instead of NameError when stdio SDK missing**. merged to main · fix tier `verified`
  - maintainer direction: category `merged`; implication `superseded`
  - files: `tests/tools/test_mcp_tool.py`, `tools/mcp_tool.py`
  - fix hunks:
  - `tests/tools/test_mcp_tool.py`

    ```diff
    @@ -1462,6 +1462,27 @@ async def _test():
     
             asyncio.run(_test())
     
    +    def test_stdio_unavailable_raises_importerror_not_nameerror(self):
    +        """Regression test for #30904.
    +
    +        When the mcp SDK isn't installed, ``_run_stdio`` previously leaked a
    +        bare ``NameError: name 'StdioServerParameters' is not defined``. The
    +        gate now raises a clear ``ImportError`` with install instructions,
    +        mirroring ``_run_http``'s behaviour when the HTTP transport is
    +        unavailable.
    +        """
    +        from tools.mcp_tool import MCPServerTask
    +
    +        server = MCPServerTask("local")
    +        config = {"command": "python3", "args": ["/tmp/echo.py"]}
    +
    +        async def _test():
    +            with patch("tools.mcp_tool._MCP_AVAILABLE", False):
    +                with pytest.raises(ImportError, match=r"mcp.*SDK"):
    +                    await server._run_stdio(config)
    +
    +        asyncio.run(_test())
    +
         def test_http_seeds_initial_protocol_header(self):
             from tools.mcp_tool import LATEST_PROTOCOL_VERSION, MCPServerTask
     
    ```
  - `tools/mcp_tool.py`

    ```diff
    @@ -1255,6 +1255,15 @@ async def _wait_for_lifecycle_event(self) -> str:
     
         async def _run_stdio(self, config: dict):
             """Run the server using stdio transport."""
    +        if not _MCP_AVAILABLE:
    +            raise ImportError(
    +                f"MCP server '{self.name}' requires the 'mcp' Python SDK, but "
    +                "it is not installed. Install with:\n"
    +                "  pip install 'hermes-agent[mcp]'\n"
    +                "or (full install):\n"
    +                "  pip install 'hermes-agent[all]'"
    +            )
    +
             command = config.get("command")
             args = config.get("args", [])
             user_env = config.get("env")
    ```
- **#30907: fix(mcp): raise clear ImportError in _run_stdio when SDK unavailable**. closed without merge
  - maintainer direction: category `superseded_by_pr`; implication `superseded`; refs `5acaeba2b`, `#31450`, `#30904`
- **#34223: fix(mcp): fail fast when sdk is missing**. open
  - maintainer direction: category `uncategorized`; implication `needs_llm`
  - files: `hermes_cli/mcp_config.py`, `tests/hermes_cli/test_mcp_config.py`, `tools/mcp_tool.py`
- **#34245: fix(mcp): fail fast with actionable error when mcp SDK missing (#34220)**. closed without merge
  - maintainer direction: category `superseded_by_pr`; implication `superseded`; refs `#105586`
- **#105586: fix(mcp): fail fast with actionable error when mcp SDK missing (salvage of #34245)**. open
  - maintainer direction: category `duplicate_of`; implication `duplicate`; refs `#34223`, `#34245`
  - files: `hermes_cli/mcp_config.py`, `tests/hermes_cli/test_mcp_config.py`

## Fix status

- Merged to main in PR #31450 (cited above). No release data is tracked. Verify downstream.
- Fix last verified (merged) `2026-05-24`.
- Subsystem: `hermes_cli`