{"record":{"id":"b983ac65bdafe68e","repo":"agentscope-ai/agentscope","slug":"gateway-failed-to-list-tools-for-mcp-self-name-r","errorCode":null,"errorMessage":"gateway failed to list tools for MCP {self.name!r}: {_safe_detail(status, body)}","messagePattern":"gateway failed to list tools for MCP (.+?): (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/agentscope/workspace/_gateway_client.py","lineNumber":330,"sourceCode":"        re-wrap them like a local :class:`MCPClient`. The unfiltered\n        list is cached; the returned list has ``enable_tools`` /\n        ``disable_tools`` applied.\n\n        Raises:\n            `RuntimeError`:\n                Gateway returned non-2xx.\n        \"\"\"\n        assert self._gateway is not None\n        status, body = await self._gateway.exec_request(\n            \"GET\",\n            f\"/mcps/{self.name}/tools\",\n            params={\n                \"agent_id\": self._agent_id,\n                \"session_id\": self._session_id,\n            },\n        )\n        if status >= 400:\n            raise RuntimeError(\n                f\"gateway failed to list tools for MCP {self.name!r}: \"\n                f\"{_safe_detail(status, body)}\",\n            )\n        data = json.loads(body)\n\n        raw_tools = [mcp.types.Tool.model_validate(d) for d in data]\n        self._cached_tools = raw_tools\n\n        # Gateway returns the unfiltered upstream view; honour the same\n        # enable/disable filtering ``MCPClient`` applies locally.\n        if self.enable_tools is not None:\n            raw_tools = [t for t in raw_tools if t.name in self.enable_tools]\n        if self.disable_tools is not None:\n            raw_tools = [\n                t for t in raw_tools if t.name not in self.disable_tools\n            ]\n        return raw_tools\n","sourceCodeStart":312,"sourceCodeEnd":348,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/workspace/_gateway_client.py#L312-L348","documentation":"Raised by GatewayMCPClient.list_raw_tools() when GET /mcps/{name}/tools through the sandbox gateway returns HTTP >= 400. The gateway could not fetch the tool list from the upstream MCP server — usually because the MCP is not connected/registered, the upstream MCP server died, or the agent/session ids don't match. Note this method is also called lazily by get_tool() on cache miss.","triggerScenarios":"`await client.list_raw_tools()` or `await client.get_tool(name)` (cache miss triggers list) when the MCP was never connect()-ed on the gateway, the upstream MCP server process exited, or the gateway returned 404/500 for the tools listing.","commonSituations":"Forgetting `await client.connect()` before tool discovery; using a GatewayMCPClient built via make_client(connected=False) without connecting; upstream MCP server (stdio/sse) crashed inside the sandbox; stale agent_id/session_id after gateway restart.","solutions":["Ensure `await client.connect()` completed successfully before listing tools / calling get_tool","Call `await gateway.health()` to confirm the gateway is alive, then `list_mcps()` to confirm the MCP is registered","Check the status/body detail in the message: 404 means unregistered, 500 usually means the upstream MCP server died — inspect gateway logs (gateway_log_path)","Re-create the client with correct agent_id/session_id if the gateway was restarted"],"exampleFix":"// before\nclient = gateway.make_client(spec)\ntools = await client.list_raw_tools()  # RuntimeError\n// after\nclient = gateway.make_client(spec)\nawait client.connect()\ntools = await client.list_raw_tools()","handlingStrategy":"try-catch","validationCode":"tools = await client.list_raw_tools()\nnames = {t.name for t in tools}\nif want not in names: ...","typeGuard":null,"tryCatchPattern":"try:\n    tools = await client.list_raw_tools()\nexcept RuntimeError as e:\n    if \"gateway failed to list tools\" in str(e):\n        # reconnect or re-register the MCP\n        await client.connect()\n    raise","preventionTips":["Always `await client.connect()` before tool discovery","Use list_mcps() to verify registration before listing tools","Wrap get_tool calls since they lazily trigger list_raw_tools"],"tags":["mcp","gateway","tool-discovery","http-4xx"],"backgroundTag":"mcp-gateway-request-failed","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}