agentscope-ai/agentscope · error · MCPRenderError

MCP {card.name!r} needs a value for: {', '.join(sorted(missi

Error message

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

What it means

After schema validation passes, render_mcp checks that every required input in card.inputs_schema has a non-missing effective value; if any are missing it raises MCPRenderError listing them. This catches required fields that were simply omitted from the values dict.

Source

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

    declared = set(card.inputs_schema.get("properties", {}))
    required = set(card.inputs_schema.get("required", []))
    missing: set[str] = set()
    config_template = card.config_template.model_dump(mode="json")
    _omit_unfilled_optional_env(
        config_template,
        values,
        declared,
        required,
    )
    config = _substitute(
        config_template,
        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 error message — it lists exactly which inputs are missing — and supply those values
2. Check card.inputs_schema['required'] and provide every listed key
3. Pin the MCP card version if the schema changed unexpectedly
4. Pre-fill defaults from the schema where available

Example fix

# before
client = render_mcp(card, values={"url": "https://api.example.com"})
# after — 'token' was required
client = render_mcp(card, values={"url": "https://api.example.com", "token": os.environ["MCP_TOKEN"]})

required = set(card.inputs_schema.get("required", []))
missing = required - {k for k, v in values.items() if v not in (None, "")}
if missing:
    raise ValueError(f"missing required MCP inputs: {sorted(missing)}")

def has_all_required(values: dict, schema: dict) -> bool:
    req = set(schema.get("required", []))
    return req <= {k for k, v in values.items() if v not in (None, "")}

try:
    client = render_mcp(card, values)
except MCPRenderError as e:
    msg = e.args[0]
    if msg.startswith("MCP") and "needs a value for" in msg:
        missing = msg.rsplit(":", 1)[1].split(",")
        # prompt user for those inputs
        ...

When it happens

Trigger: Calling install_mcp/update_mcp without supplying all required inputs declared in the card's required array — e.g. forgetting an API key or endpoint input that has no default.

Common situations: New version of an MCP card marks previously-optional inputs as required; UI form not rendering every required field; automations built against an older card schema omitting newly required values.

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

• Invalid values for MCP {card.name!r}: {e.message}
• STDIO MCP does not support ephemeral mode. Use 'shared' or '
• MCP {card.name!r} produced an invalid client: {e}
• MCPClient name '{self.name}' contains characters not allowed
• STDIO MCP must be stateful (is_stateful=True).

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