agentscope-ai/agentscope · error · MCPRenderError

MCP produced an invalid client

Error message

MCP {card.name!r} produced an invalid client: {e}

What it means

If the values pass schema and required checks but MCPClient(...) construction raises ValueError, render_mcp wraps it as MCPRenderError with the client's message. The rendered config itself is structurally invalid for the MCP client (bad URL, unsupported transport fields, malformed headers, etc.).

Solutions

1. Read the wrapped ValueError message — it names the invalid config field
2. Normalize inputs (strip whitespace, add URL scheme) before rendering
3. Check MCPClient's accepted transport/field names for your agentscope version
4. Add a unit test that renders the card with representative values to catch config drift

Example fix

# before
client = render_mcp(card, values={"url": "example.com/mcp"})
# after
client = render_mcp(card, values={"url": "https://example.com/mcp"})

from yarl import URL
u = URL(values["url"])
if not u.is_absolute():
    raise ValueError("MCP url must include scheme, e.g. https://...")

def is_valid_mcp_url(url: str) -> bool:
    from yarl import URL
    u = URL(url.strip())
    return u.is_absolute() and u.scheme in {"http", "https"}

try:
    client = render_mcp(card, values)
except MCPRenderError as e:
    if "invalid client" in e.args[0]:
        # log values (redact secrets), fix config per inner message
        ...

When it happens

Trigger: Values that type-check but produce an invalid mcp_config — e.g. a malformed URL, invalid transport type string, or header/env entries the MCPClient constructor rejects via ValueError.

Common situations: URLs missing a scheme (example.com instead of https://example.com), trailing whitespace in endpoints, unsupported transport names after a library upgrade, or templated env values that render to empty strings.

Related errors

• BubblewrapWorkspace currently requires share_net=True…
• "build_mem0_config requires `chat_model` and…
• DimensionPolicy: kind=ANY requires dimension=None, got…
• DimensionPolicy: kind=
• Either client_gen or session must be provided, but not both.

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

Appendix: source

Thrown at src/agentscope/app/_service/_mcp_render.py:166

        values,
        declared,
        missing,
    )

    if missing:
        raise MCPRenderError(
            f"MCP {card.name!r} needs a value for: "
            f"{', '.join(sorted(missing))}",
        )

    try:
        return MCPClient(
            name=name or card.name,
            is_stateful=card.is_stateful,
            mcp_config=config,
        )
    except ValueError as e:
        raise MCPRenderError(
            f"MCP {card.name!r} produced an invalid client: {e}",
        ) from e

View on GitHub (pinned to e90f1c7592)