agentscope-ai/agentscope · error · HTTPException

name required

Error message

name required

What it means

Raised as HTTP 400 by the gateway's _add_mcp when the JSON body of POST /mcps lacks a non-empty 'name' field. Every registered MCP client must be named so it can be addressed later by /mcps/{name}. It is a simple request-validation error.

Source

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

    async def _list_mcps(
        agent_id: str = "",
        session_id: str = "",
    ) -> list[dict[str, Any]]:
        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(

View on GitHub (pinned to e90f1c7592)

Solutions

1. Include a non-empty "name" string in the JSON body of POST /mcps.
2. Ensure Content-Type: application/json so await request.json() parses.
3. Check for typos like "Name" or "server_name" in the payload key.

Example fix

# before
await client.post("/mcps", json={"url": "http://localhost:8080/mcp"})

# after
await client.post("/mcps", json={"name": "my-server", "url": "http://localhost:8080/mcp"})

def mcp_add_body_ok(body: dict) -> bool:
    return isinstance(body.get("name"), str) and body["name"].strip() != ""

r = await client.post("/mcps", json=body)
if r.status_code == 400 and "name required" in r.text:
    body.setdefault("name", "my-server")
    r = await client.post("/mcps", json=body)

When it happens

Trigger: POST /mcps with body {} , {"name": ""}, {"name": null}, or a body where the key is misspelled (e.g. 'server' instead of 'name').

Common situations: Client sends the connection config (url/command) but forgets the name field, or serializes the name as null/empty string; also sending form-encoded instead of JSON so body.get('name') yields nothing.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

• {name!r} not found for agent={agent_id!r} session={session_i
• {name!r} already exists for agent={agent_id!r} session={sess
• connect failed: {e}
• {e}
• Input validation failed for tool '{tool_call.name}': {e.mess

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