{"record":{"id":"d9b2c665bed79661","repo":"agentscope-ai/agentscope","slug":"stdio-mcp-does-not-support-ephemeral-mode-use-sh","errorCode":null,"errorMessage":"STDIO MCP does not support ephemeral mode. Use 'shared' or 'isolated' instead.","messagePattern":"STDIO MCP does not support ephemeral mode\\. Use 'shared' or 'isolated' instead\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/agentscope/app/_router/_schema/_mcp.py","lineNumber":68,"sourceCode":"\n    mcp_config: StdioMCPConfig | HttpMCPConfig = Field(\n        discriminator=\"type\",\n        title=\"MCP Config\",\n        description=\"The base MCP server configuration.\",\n    )\n\n    def validate_config(self) -> None:\n        \"\"\"Validate the configuration.\n\n        Raises:\n            ValueError: If the configuration is invalid.\n        \"\"\"\n        # STDIO MCP cannot use ephemeral mode\n        if (\n            self.mcp_config.type == \"stdio_mcp\"\n            and self.connection_scope == ConnectionScope.EPHEMERAL\n        ):\n            raise ValueError(\n                \"STDIO MCP does not support ephemeral mode. \"\n                \"Use 'shared' or 'isolated' instead.\",\n            )\n\n\nclass MCPCreateRequest(MCPBase):\n    \"\"\"Request body for creating a new MCP configuration.\n\n    Used in POST /mcp endpoint. Does not include server-generated fields\n    like creator_id, created_at, updated_at.\n    \"\"\"\n\n\nclass MCPUpdateRequest(BaseModel):\n    \"\"\"Request body for partially updating an MCP configuration.\n\n    Used in PATCH /mcp/{name} endpoint. All fields are optional.\n    \"\"\"","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/app/_router/_schema/_mcp.py#L50-L86","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set connection_scope to 'shared' or 'isolated' for stdio_mcp configs.","If you truly need per-request lifetimes, use an SSE/HTTP MCP type instead of stdio.","Upgrade/re-read the MCP schema docs to confirm the allowed scope values for your version."],"exampleFix":"# before\n{\"mcp_config\": {\"type\": \"stdio_mcp\", \"command\": \"uvx\", \"args\": [...]}, \"connection_scope\": \"ephemeral\"}\n# after\n{\"mcp_config\": {\"type\": \"stdio_mcp\", \"command\": \"uvx\", \"args\": [...]}, \"connection_scope\": \"isolated\"}","handlingStrategy":"validation","validationCode":"def validate_mcp(cfg):\n    if cfg[\"mcp_config\"][\"type\"] == \"stdio_mcp\" and cfg.get(\"connection_scope\") == \"ephemeral\":\n        cfg[\"connection_scope\"] = \"isolated\"\n    return cfg","typeGuard":"const isValidMcp = (c) => !(c.mcp_config?.type === 'stdio_mcp' && c.connection_scope === 'ephemeral');","tryCatchPattern":"try: create_mcp(cfg) except ValueError as e: if 'ephemeral' in str(e): cfg['connection_scope']='isolated'; retry()","preventionTips":["Template per MCP type with correct scope preset","Validate config client-side before submit"],"tags":["mcp","validation","stdio","config-error","valueerror"],"backgroundTag":"schema-validation-failed","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}