{"record":{"id":"073463f6b3af133d","repo":"agentscope-ai/agentscope","slug":"stdio-mcp-must-be-stateful-is-stateful-true","errorCode":null,"errorMessage":"STDIO MCP must be stateful (is_stateful=True).","messagePattern":"STDIO MCP must be stateful \\(is_stateful=True\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/agentscope/mcp/_mcp_client.py","lineNumber":131,"sourceCode":"        Returns:\n            True if connected, False otherwise.\n        \"\"\"\n        return self._is_connected\n\n    def model_post_init(self, __context: Any) -> None:\n        \"\"\"Validate configuration and initialize client.\"\"\"\n        # MCP name is used to compose model-facing tool names\n        # (mcp__{name}__{tool}), which must match ^[a-zA-Z0-9_-]+$.\n        if not re.fullmatch(r\"[a-zA-Z0-9_-]+\", self.name):\n            raise ValueError(\n                f\"MCPClient name '{self.name}' contains characters not \"\n                f\"allowed by LLM providers (only [a-zA-Z0-9_-] are \"\n                f\"permitted). Please rename it.\",\n            )\n\n        # STDIO MCP must be stateful\n        if self.mcp_config.type == \"stdio_mcp\" and not self.is_stateful:\n            raise ValueError(\n                \"STDIO MCP must be stateful (is_stateful=True).\",\n            )\n\n        # Check arguments for self.enable_tools and disable_tools\n        if self.enable_tools is not None:\n            if not isinstance(self.enable_tools, list) or any(\n                not isinstance(_, str) for _ in self.enable_tools\n            ):\n                raise ValueError(\n                    \"Enable tools should be a list of strings, but got \"\n                    f\"{self.enable_tools}.\",\n                )\n\n        if self.disable_tools is not None:\n            if not isinstance(self.disable_tools, list) or any(\n                not isinstance(_, str) for _ in self.disable_tools\n            ):\n                raise ValueError(","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/mcp/_mcp_client.py#L113-L149","documentation":"STDIO-based MCP servers run as a local subprocess whose process state persists across tool calls, so they cannot operate statelessly. MCPClient's post-init validation enforces that a stdio_mcp configuration requires is_stateful=True.","triggerScenarios":"MCPClient(mcp_config=MCPConfig(type=\"stdio_mcp\", ...), is_stateful=False) — explicitly setting is_stateful=False or using a stateless preset/template with a stdio transport.","commonSituations":"Copying a stateless HTTP/SSE MCPClient configuration and swapping in a stdio command without flipping is_stateful; library examples defaulting to stateless for simplicity.","solutions":["Set is_stateful=True (or omit it if the default is True for stdio) for stdio_mcp configs","If you intended stateless operation, use an HTTP/SSE/streamable transport type instead of stdio_mcp"],"exampleFix":"// before\nclient = MCPClient(\n    name=\"fs\",\n    mcp_config=MCPConfig(type=\"stdio_mcp\", command=\"npx\", args=[\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/tmp\"]),\n    is_stateful=False,\n)\n\n// after\nclient = MCPClient(\n    name=\"fs\",\n    mcp_config=MCPConfig(type=\"stdio_mcp\", command=\"npx\", args=[\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/tmp\"]),\n    is_stateful=True,\n)","handlingStrategy":"validation","validationCode":"if cfg.type == \"stdio_mcp\":\n    is_stateful = True  # forced\nclient = MCPClient(name=n, mcp_config=cfg, is_stateful=is_stateful)","typeGuard":null,"tryCatchPattern":"try:\n    MCPClient(name=n, mcp_config=cfg, is_stateful=False)\nexcept ValueError as e:\n    if \"must be stateful\" in str(e):\n        client = MCPClient(name=n, mcp_config=cfg, is_stateful=True)","preventionTips":["Remember the transport/statefulness matrix: stdio implies stateful","Write a helper that infers is_stateful from the transport type","Document the constraint next to stdio MCP examples in your codebase"],"tags":["mcp","stdio","state-management","validation"],"backgroundTag":"config-validation-failed","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}