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.

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

• not found for agent= session=
• connect failed
• already exists for agent= session=
• name required
• gateway failed to list MCPs

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

Appendix: 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)