agentscope-ai/agentscope · error · MCPRenderError

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

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.).

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)

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

• The injection template must contain the '{runtime_state}' pl
• STDIO MCP does not support ephemeral mode. Use 'shared' or '
• Invalid values for MCP {card.name!r}: {e.message}
• MCP {card.name!r} needs a value for: {', '.join(sorted(missi
• DimensionPolicy: kind=ANY requires dimension=None, got dimen

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