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.

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).
• Either client_gen or session must be provided, but not both.
• Invalid values for MCP
• MCP needs a value for
• MCP produced an invalid client

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

Appendix: 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)