What causes "{name!r} not found for agent={agent_id!r} session={session_id!r}" in agentscope-ai/agentscope?

Re-add the MCP via POST /mcps with the same agent_id and session_id you use for tool calls.

agentscope-ai/agentscope · error · HTTPException

{name!r} not found for agent={agent_id!r} session={session_i

Error message

{name!r} not found for agent={agent_id!r} session={session_id!r}

What it means

Raised as HTTP 404 by the agentscope MCP gateway when a lookup for a named MCP client fails for the given (agent_id, session_id) pair. The gateway keeps clients in a nested dict keyed by (agent_id, session_id) then name; any tool/list/call/remove request for an unregistered name hits this. It means the MCP server was never added, was removed, or belongs to a different agent/session scope.

Source

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

    if client.is_stateful:
        await client.connect()
    await client.list_raw_tools()
    return client


def _build_app(
    state: _State,
    auth_token: str | None = None,
    instance_nonce: str | None = None,
) -> FastAPI:
    """Build the FastAPI app with all routes wired against ``state``."""
    app = FastAPI(title="agentscope-workspace-mcp-gateway")

    def _lookup(agent_id: str, session_id: str, name: str) -> MCPClient:
        """Resolve one registered client or raise 404."""
        client = state.clients.get((agent_id, session_id), {}).get(name)
        if client is None:
            raise HTTPException(
                404,
                f"{name!r} not found for agent={agent_id!r} "
                f"session={session_id!r}",
            )
        return client

    if auth_token:

        @app.middleware("http")
        async def _auth_middleware(request: Request, call_next: Any) -> Any:
            if request.url.path == "/health":
                return await call_next(request)
            header = request.headers.get("authorization", "")
            expected = f"Bearer {auth_token}"
            valid = (
                header.isascii()
                and expected.isascii()
                and secrets.compare_digest(header, expected)

View on GitHub (pinned to e90f1c7592)

Solutions

Re-add the MCP via POST /mcps with the same agent_id and session_id you use for tool calls.
Verify registration with the list endpoint before calling tools.
Check exact spelling and case of name in the URL vs what you passed to _add_mcp.
If the gateway restarted (in-memory state), re-register all needed MCPs on startup.

Example fix

# before
client.post("/mcps/my-server/call", ...)  # 404

# after
await client.post("/mcps?agent_id=a1&session_id=s1", json={"name": "my-server", ...})
await client.post("/mcps/my-server/call?agent_id=a1&session_id=s1", json={"tool": "echo", "arguments": {}})

Defensive patterns

Strategy: try-catch

Try / catch

resp = await client.get(f"/mcps/{name}/tools", params={"agent_id": aid, "session_id": sid})
if resp.status_code == 404:
    resp = await client.post("/mcps", params={"agent_id": aid, "session_id": sid}, json=config)

Prevention

Always pass the same agent_id and session_id to add and call endpoints.
Re-register MCPs automatically on gateway startup since state is in-memory.
Centralize MCP names as constants to avoid typos.

When it happens

Trigger: GET /tools, POST /call, or DELETE /mcps/{name} where name was never registered via POST /mcps for the same agent_id + session_id; calling after a successful DELETE; or using mismatched agent_id/session_id query params between add and call.

Common situations: Session restarted so the in-memory registry was lost (gateway process restart), typo in the MCP name, forgetting that agent_id/session_id default to "" so an add with explicit ids can't be found by a call without those ids.

Related errors

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