agentscope-ai/agentscope · error · ValueError

STDIO MCP does not support ephemeral mode. Use 'shared' or '

Error message

STDIO MCP does not support ephemeral mode. Use 'shared' or 'isolated' instead.

What it means

Raised when validating an MCP configuration: a stdio_mcp type connection is combined with connection_scope='ephemeral'. STDIO MCP servers are subprocesses, so ephemeral (per-request) scoping is unsupported; the schema validator rejects it with a ValueError before the request reaches storage.

Source

Thrown at src/agentscope/app/_router/_schema/_mcp.py:68

    mcp_config: StdioMCPConfig | HttpMCPConfig = Field(
        discriminator="type",
        title="MCP Config",
        description="The base MCP server configuration.",
    )

    def validate_config(self) -> None:
        """Validate the configuration.

        Raises:
            ValueError: If the configuration is invalid.
        """
        # STDIO MCP cannot use ephemeral mode
        if (
            self.mcp_config.type == "stdio_mcp"
            and self.connection_scope == ConnectionScope.EPHEMERAL
        ):
            raise ValueError(
                "STDIO MCP does not support ephemeral mode. "
                "Use 'shared' or 'isolated' instead.",
            )


class MCPCreateRequest(MCPBase):
    """Request body for creating a new MCP configuration.

    Used in POST /mcp endpoint. Does not include server-generated fields
    like creator_id, created_at, updated_at.
    """


class MCPUpdateRequest(BaseModel):
    """Request body for partially updating an MCP configuration.

    Used in PATCH /mcp/{name} endpoint. All fields are optional.
    """

View on GitHub (pinned to e90f1c7592)

Solutions

1. Set connection_scope to 'shared' or 'isolated' for stdio_mcp configs.
2. If you truly need per-request lifetimes, use an SSE/HTTP MCP type instead of stdio.
3. Upgrade/re-read the MCP schema docs to confirm the allowed scope values for your version.

Example fix

# before
{"mcp_config": {"type": "stdio_mcp", "command": "uvx", "args": [...]}, "connection_scope": "ephemeral"}
# after
{"mcp_config": {"type": "stdio_mcp", "command": "uvx", "args": [...]}, "connection_scope": "isolated"}

def validate_mcp(cfg):
    if cfg["mcp_config"]["type"] == "stdio_mcp" and cfg.get("connection_scope") == "ephemeral":
        cfg["connection_scope"] = "isolated"
    return cfg

const isValidMcp = (c) => !(c.mcp_config?.type === 'stdio_mcp' && c.connection_scope === 'ephemeral');

try: create_mcp(cfg) except ValueError as e: if 'ephemeral' in str(e): cfg['connection_scope']='isolated'; retry()

When it happens

Trigger: POST/PUT of an MCP config with {"mcp_config": {"type": "stdio_mcp", ...}} and "connection_scope": "ephemeral". Typically hit when copy-pasting an SSE/HTTP MCP template and only changing the type field.

Common situations: Templates defaulting to ephemeral scope; migrating an HTTP MCP config to stdio without updating scope; UI form that keeps a previously selected scope after switching protocol type.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• STDIO MCP must be stateful (is_stateful=True).
• Invalid values for MCP {card.name!r}: {e.message}
• MCP {card.name!r} needs a value for: {', '.join(sorted(missi
• MCP {card.name!r} produced an invalid client: {e}
• MCPClient name '{self.name}' contains characters not allowed

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