agentscope-ai/agentscope · warning · HTTPException

{name!r} already exists for agent={agent_id!r} session={sess

Error message

{name!r} already exists for agent={agent_id!r} session={session_id!r}

What it means

Raised as HTTP 409 by _add_mcp when the requested name already exists in the registry for the same (agent_id, session_id). The gateway disallows duplicate names within one session so /mcps/{name} stays unambiguous.

Source

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

        return [
            c.model_dump(mode="json")
            for c in state.clients.get((agent_id, session_id), {}).values()
        ]

    @app.post("/mcps")
    async def _add_mcp(
        request: Request,
        agent_id: str = "",
        session_id: str = "",
    ) -> dict[str, Any]:
        body = await request.json()
        name = body.get("name", "")
        if not name:
            raise HTTPException(400, "name required")
        async with state.lock:
            by_name = state.clients.setdefault((agent_id, session_id), {})
            if name in by_name:
                raise HTTPException(
                    409,
                    f"{name!r} already exists for agent={agent_id!r} "
                    f"session={session_id!r}",
                )
            try:
                by_name[name] = await _build_client(body)
            except HTTPException:
                raise
            except Exception as e:  # noqa: BLE001
                raise HTTPException(500, f"connect failed: {e}") from e
        return {"ok": True}

    @app.delete("/mcps/{name}")
    async def _remove_mcp(
        name: str,
        agent_id: str = "",
        session_id: str = "",
    ) -> dict[str, Any]:

View on GitHub (pinned to e90f1c7592)

Solutions

1. DELETE /mcps/{name} before re-adding, or pick a unique name per registration.
2. Make registration idempotent: catch 409 and treat it as success if the config is unchanged.
3. List existing MCPs first and skip names already registered.

Example fix

# before
await client.post("/mcps", json={"name": "my-server", ...})  # 2nd time -> 409

# after
r = await client.post("/mcps", json={"name": "my-server", ...})
if r.status_code == 409:
    await client.delete("/mcps/my-server")
    r = await client.post("/mcps", json={"name": "my-server", ...})

r = await client.post("/mcps", json=config)
if r.status_code == 409:
    await client.delete(f"/mcps/{config['name']}")
    r = await client.post("/mcps", json=config)

When it happens

Trigger: POST /mcps with a name already added for the same agent_id/session_id, e.g. re-running registration code without removing the previous entry or without checking existence first.

Common situations: Retried registration after a network hiccup, hot-reload of client code that re-registers on every startup, or copy-pasted setup blocks registering the same server twice.

Related errors

• {name!r} not found for agent={agent_id!r} session={session_i
• name required
• connect failed: {e}
• {e}
• gateway failed to remove MCP {self.name!r}: {_safe_detail(st

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