{"record":{"id":"badba8af0557ccb9","repo":"microsoft/semantic-kernel","slug":"failed-to-connect-to-the-mcp-server-please-check","errorCode":null,"errorMessage":"Failed to connect to the MCP server. Please check your configuration.","messagePattern":"Failed to connect to the MCP server\\. Please check your configuration\\.","errorType":"exception","errorClass":"KernelPluginInvalidConfigurationError","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/connectors/mcp.py","lineNumber":329,"sourceCode":"        \"\"\"Disconnect from the MCP server.\"\"\"\n        if self._stop_event:\n            # Signal the stop event, which asks the _inner_connect\n            # method to close the session with the exit stack\n            self._stop_event.set()\n        if self._current_task:\n            # After, the signal, we wait for it to close the exit stack.\n            await self._current_task\n            self._current_task = None\n        self.session = None\n\n    async def _inner_connect(self, ready_event: asyncio.Event) -> None:\n        if not self.session:\n            try:\n                transport = await self._exit_stack.enter_async_context(self.get_mcp_client())\n            except Exception as ex:\n                await self._exit_stack.aclose()\n                ready_event.set()\n                raise KernelPluginInvalidConfigurationError(\n                    \"Failed to connect to the MCP server. Please check your configuration.\"\n                ) from ex\n            try:\n                session = await self._exit_stack.enter_async_context(\n                    ClientSession(\n                        read_stream=transport[0],\n                        write_stream=transport[1],\n                        read_timeout_seconds=timedelta(seconds=self.request_timeout) if self.request_timeout else None,\n                        message_handler=self.message_handler,\n                        logging_callback=self.logging_callback,\n                        sampling_callback=self.sampling_callback,\n                    )\n                )\n            except Exception as ex:\n                await self._exit_stack.aclose()\n                raise KernelPluginInvalidConfigurationError(\n                    \"Failed to create a session. Please check your configuration.\"\n                ) from ex","sourceCodeStart":311,"sourceCodeEnd":347,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/connectors/mcp.py#L311-L347","documentation":"Thrown by MCPPluginBase._inner_connect (mcp.py:329) as a KernelPluginInvalidConfigurationError when self.get_mcp_client() fails to produce a transport. get_mcp_client returns the stdio/SSE/streamable client context manager; a failure here means the transport could not be created at all. The exit stack is closed and the ready_event is set before re-raising.","triggerScenarios":"For MCPStdioPlugin: the command/executable does not exist, is not on PATH, or lacks execute permission. For MCPStreamablePlugin/MCPStdioClient variants: an invalid URL, unreachable host, TLS failure, or missing required env. The exception originates at mcp.py:325-331.","commonSituations":"Wrong command path or args in MCPStdioPlugin (e.g. 'npx' not installed, wrong package name); missing environment variables the server needs; firewall/proxy blocking an SSE/streamable endpoint; wrong port; typo in URL; server binary not built.","solutions":["Verify the command runs standalone in a shell with the same env (e.g. execute the stdio command manually).","Check that any required environment variables (API keys, PATH) are passed to the plugin.","Confirm the URL scheme/host/port for HTTP transports; test with curl against the endpoint.","Inspect the chained __cause__ for the precise OS or network error (FileNotFoundError, ConnectionError, etc.)."],"exampleFix":"# before\nplugin = MCPStdioPlugin(name=\"x\", command=\"npx\", args=[\"-y\", \"@some/nonexistent-server\"])\n\n# after (verify command resolves; pin a real package)\nplugin = MCPStdioPlugin(name=\"x\", command=\"npx\", args=[\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/tmp\"])","handlingStrategy":"validation","validationCode":"import shutil, os\n\ndef stdio_command_is_runnable(command: str, args: list[str], env: dict | None = None) -> bool:\n    if \"/\" in command:\n        return os.path.isfile(command) and os.access(command, os.X_OK)\n    return shutil.which(command) is not None","typeGuard":"import anyio\n\nasync def url_reachable(url: str) -> bool:\n    try:\n        async with anyio.connect(\"host\", port):\n            return True\n    except OSError:\n        return False","tryCatchPattern":"from semantic_kernel.exceptions.kernel_exceptions import KernelPluginInvalidConfigurationError\n\ntry:\n    async with MCPStdioPlugin(name=\"x\", command=\"npx\", args=[...]) as plugin:\n        ...\nexcept KernelPluginInvalidConfigurationError as ex:\n    if \"Failed to connect to the MCP server\" in str(ex):\n        cause = ex.__cause__  # FileNotFoundError / ConnectionError\n        log.error(\"transport init failed: %r\", cause)","preventionTips":["Run the server command manually in a shell with the same env before wiring it into the plugin.","Pass required env vars (API keys, PATH) explicitly to the plugin.","For HTTP transports, curl the endpoint first to confirm reachability.","Inspect __cause__ for the precise OS/network error."],"tags":["mcp","connection","transport","stdio","configuration"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}