microsoft/semantic-kernel · error · KernelPluginInvalidConfigurationError

Failed to connect to the MCP server. Please check your confi

Error message

Failed to connect to the MCP server. Please check your configuration.

What it means

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.

Source

Thrown at python/semantic_kernel/connectors/mcp.py:329

        """Disconnect from the MCP server."""
        if self._stop_event:
            # Signal the stop event, which asks the _inner_connect
            # method to close the session with the exit stack
            self._stop_event.set()
        if self._current_task:
            # After, the signal, we wait for it to close the exit stack.
            await self._current_task
            self._current_task = None
        self.session = None

    async def _inner_connect(self, ready_event: asyncio.Event) -> None:
        if not self.session:
            try:
                transport = await self._exit_stack.enter_async_context(self.get_mcp_client())
            except Exception as ex:
                await self._exit_stack.aclose()
                ready_event.set()
                raise KernelPluginInvalidConfigurationError(
                    "Failed to connect to the MCP server. Please check your configuration."
                ) from ex
            try:
                session = await self._exit_stack.enter_async_context(
                    ClientSession(
                        read_stream=transport[0],
                        write_stream=transport[1],
                        read_timeout_seconds=timedelta(seconds=self.request_timeout) if self.request_timeout else None,
                        message_handler=self.message_handler,
                        logging_callback=self.logging_callback,
                        sampling_callback=self.sampling_callback,
                    )
                )
            except Exception as ex:
                await self._exit_stack.aclose()
                raise KernelPluginInvalidConfigurationError(
                    "Failed to create a session. Please check your configuration."
                ) from ex

View on GitHub (pinned to c028a0c7dc)

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.).

Example fix

# before
plugin = MCPStdioPlugin(name="x", command="npx", args=["-y", "@some/nonexistent-server"])

# after (verify command resolves; pin a real package)
plugin = MCPStdioPlugin(name="x", command="npx", args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"])

Defensive patterns

Strategy: validation

Validate before calling

import shutil, os

def stdio_command_is_runnable(command: str, args: list[str], env: dict | None = None) -> bool:
    if "/" in command:
        return os.path.isfile(command) and os.access(command, os.X_OK)
    return shutil.which(command) is not None

Type guard

import anyio

async def url_reachable(url: str) -> bool:
    try:
        async with anyio.connect("host", port):
            return True
    except OSError:
        return False

Try / catch

from semantic_kernel.exceptions.kernel_exceptions import KernelPluginInvalidConfigurationError

try:
    async with MCPStdioPlugin(name="x", command="npx", args=[...]) as plugin:
        ...
except KernelPluginInvalidConfigurationError as ex:
    if "Failed to connect to the MCP server" in str(ex):
        cause = ex.__cause__  # FileNotFoundError / ConnectionError
        log.error("transport init failed: %r", cause)

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/badba8af0557ccb9. Report an issue: GitHub.