agentscope-ai/agentscope · error · RuntimeError

gateway failed to list MCPs: {_safe_detail(status, body)}

Error message

gateway failed to list MCPs: {_safe_detail(status, body)}

What it means

Raised by GatewayClient.list_mcps() when GET /mcps through the sandbox shim returns HTTP >= 400. The gateway inside the sandbox refused or failed the listing request — commonly an auth failure (bad/missing bearer token), a gateway crash, or an internal error serializing MCP specs. The message embeds the status and truncated body via _safe_detail.

Source

Thrown at src/agentscope/workspace/_gateway_client.py:529

        maintaining their upstream sessions.

        Args:
            agent_id (`str`, defaults to ``""``):
                The agent whose MCP clients to fetch.
            session_id (`str`, defaults to ``""``):
                The session whose MCP clients to fetch.

        Raises:
            `RuntimeError`:
                Gateway returned non-2xx.
        """
        status, body = await self.exec_request(
            "GET",
            "/mcps",
            params={"agent_id": agent_id, "session_id": session_id},
        )
        if status >= 400:
            raise RuntimeError(
                f"gateway failed to list MCPs: {_safe_detail(status, body)}",
            )
        specs = json.loads(body)
        return [
            self.make_client(
                spec,
                agent_id=agent_id,
                session_id=session_id,
                connected=True,
            )
            for spec in specs
        ]

    def make_client(
        self,
        spec: dict[str, Any],
        *,
        agent_id: str = "",

View on GitHub (pinned to e90f1c7592)

Solutions

1. Check the status/body in the message: 401/403 → fix auth_token; 500 → read gateway logs via gateway_log_path
2. Verify gateway liveness with `await gateway.health()`
3. Confirm gateway_port points at the right in-sandbox process (no port collision)
4. Upgrade/redeploy so the host library and in-sandbox gateway versions match

if not await gateway.health():
    raise RuntimeError("gateway unreachable")

try:
    mcps = await gateway.list_mcps(agent_id, session_id)
except RuntimeError as e:
    logger.error("list_mcps failed: %s", e)
    mcps = []

When it happens

Trigger: `await gateway.list_mcps(agent_id, session_id)` when the auth token configured on GatewayClient doesn't match the gateway, the gateway process crashed mid-request, or the gateway returned 500 while dumping MCP specs.

Common situations: Wrong auth_token after gateway restart with a regenerated token; gateway version mismatch between host shim script and in-sandbox server; port collision where 127.0.0.1:gateway_port inside the sandbox is served by a different process; gateway restarted and lost all state (still 200 usually, but 500 possible on partial init).

Related errors

• gateway failed to remove MCP {self.name!r}: {_safe_detail(st
• gateway failed to list tools for MCP {self.name!r}: {_safe_d
• {name!r} not found for agent={agent_id!r} session={session_i
• name required
• {name!r} already exists for agent={agent_id!r} session={sess

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/8ee5487a2cbd5f1e. Report an issue: GitHub.