{"record":{"id":"7c016e447c1556f8","repo":"agentscope-ai/agentscope","slug":"name-r-not-found-for-agent-agent-id-r-session","errorCode":null,"errorMessage":"{name!r} not found for agent={agent_id!r} session={session_id!r}","messagePattern":"(.+?) not found for agent=(.+?) session=(.+?)","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"error","filePath":"src/agentscope/workspace/_mcp_gateway/_mcp_gateway_app.py","lineNumber":73,"sourceCode":"    if client.is_stateful:\n        await client.connect()\n    await client.list_raw_tools()\n    return client\n\n\ndef _build_app(\n    state: _State,\n    auth_token: str | None = None,\n    instance_nonce: str | None = None,\n) -> FastAPI:\n    \"\"\"Build the FastAPI app with all routes wired against ``state``.\"\"\"\n    app = FastAPI(title=\"agentscope-workspace-mcp-gateway\")\n\n    def _lookup(agent_id: str, session_id: str, name: str) -> MCPClient:\n        \"\"\"Resolve one registered client or raise 404.\"\"\"\n        client = state.clients.get((agent_id, session_id), {}).get(name)\n        if client is None:\n            raise HTTPException(\n                404,\n                f\"{name!r} not found for agent={agent_id!r} \"\n                f\"session={session_id!r}\",\n            )\n        return client\n\n    if auth_token:\n\n        @app.middleware(\"http\")\n        async def _auth_middleware(request: Request, call_next: Any) -> Any:\n            if request.url.path == \"/health\":\n                return await call_next(request)\n            header = request.headers.get(\"authorization\", \"\")\n            expected = f\"Bearer {auth_token}\"\n            valid = (\n                header.isascii()\n                and expected.isascii()\n                and secrets.compare_digest(header, expected)","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/workspace/_mcp_gateway/_mcp_gateway_app.py#L55-L91","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nclient.post(\"/mcps/my-server/call\", ...)  # 404\n\n# after\nawait client.post(\"/mcps?agent_id=a1&session_id=s1\", json={\"name\": \"my-server\", ...})\nawait client.post(\"/mcps/my-server/call?agent_id=a1&session_id=s1\", json={\"tool\": \"echo\", \"arguments\": {}})","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"resp = await client.get(f\"/mcps/{name}/tools\", params={\"agent_id\": aid, \"session_id\": sid})\nif resp.status_code == 404:\n    resp = await client.post(\"/mcps\", params={\"agent_id\": aid, \"session_id\": sid}, json=config)","preventionTips":["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."],"tags":["agentscope","mcp","gateway","http-404","not-found"],"backgroundTag":"http-404-not-found","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}