agentscope-ai/agentscope · error · HTTPException

{e}

Error message

{e}

What it means

Raised as HTTP 404 by _call_tool when client.get_tool(tool) or the tool invocation raises ValueError — the MCP layer signals 'unknown tool' via ValueError, which the gateway maps to 404 with the original message. It means the connected MCP server does not expose a tool with that name.

Source

Thrown at src/agentscope/workspace/_mcp_gateway/_mcp_gateway_app.py:182

        raw = await client.list_raw_tools()
        return [t.model_dump(mode="json") for t in raw]

    @app.post("/mcps/{name}/tools/{tool}")
    async def _call_tool(
        name: str,
        tool: str,
        request: Request,
        agent_id: str = "",
        session_id: str = "",
    ) -> dict[str, Any]:
        client = _lookup(agent_id, session_id, name)
        body = await request.json()
        arguments = body.get("arguments") or {}
        try:
            tool_obj = await client.get_tool(tool)
            chunk = await tool_obj(**arguments)
        except ValueError as e:
            raise HTTPException(404, str(e)) from e
        except Exception as e:  # noqa: BLE001
            raise HTTPException(500, str(e)) from e
        return {"chunk": chunk.model_dump(mode="json")}

    return app


async def _run(
    port: int,
    auth_token: str | None = None,
    instance_nonce: str | None = None,
) -> None:
    """Start uvicorn on an empty registry, clean up upstreams on exit."""
    state = _State()
    app = _build_app(
        state,
        auth_token=auth_token,
        instance_nonce=instance_nonce,

View on GitHub (pinned to e90f1c7592)

Solutions

1. List tools for the registered client first and use an exact name from the result.
2. Update the tool name after server upgrades; check the server's changelog.
3. Confirm you registered the intended server under this name (a wrong server may expose different tools).
4. Re-register the client if the server changed its tool set since registration.

Example fix

# before
await client.post("/mcps/srv/call", json={"tool": "summarise", "arguments": {}})  # 404 unknown tool

# after
tools = await client.get("/mcps/srv/tools")
# use exact name, e.g. "summarize"
await client.post("/mcps/srv/call", json={"tool": "summarize", "arguments": {}})

tools_resp = await client.get(f"/mcps/{name}/tools", params={"agent_id": aid, "session_id": sid})
known = {t["name"] for t in tools_resp.json().get("tools", [])}
if tool not in known:
    raise SystemExit(f"unknown tool {tool}; available: {sorted(known)}")

r = await client.post(f"/mcps/{name}/call", json={"tool": tool, "arguments": args})
if r.status_code == 404:
    tools = await client.get(f"/mcps/{name}/tools")
    raise KeyError(f"{tool} not in {[t['name'] for t in tools.json()['tools']]}")

When it happens

Trigger: POST call with a tool name not offered by the registered MCP server, or calling before the server's tool list was refreshed so stale/renamed tools are referenced.

Common situations: Server updated and tool renamed/removed, typo in tool name, calling a tool from a different MCP server than the one registered under this name.

Related errors

• {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
• connect failed: {e}
• Tool '{name}' not found in MCP server '{self.name}'

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