microsoft/semantic-kernel · error · KernelPluginInvalidConfigurationError

Failed to initialize session. Please check your configuratio

Error message

Failed to initialize session. Please check your configuration.

What it means

Thrown by MCPPluginBase._inner_connect (mcp.py:352) as a KernelPluginInvalidConfigurationError when session.initialize() fails. initialize() performs the MCP capability handshake (protocol version negotiation, capabilities exchange). A failure here means the server answered the transport but the handshake did not complete successfully.

Source

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

                    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
            try:
                await session.initialize()
            except Exception as ex:
                await self._exit_stack.aclose()
                raise KernelPluginInvalidConfigurationError(
                    "Failed to initialize session. Please check your configuration."
                ) from ex
            self.session = session
        elif self.session._request_id == 0:
            # If the session is not initialized, we need to reinitialize it
            await self.session.initialize()
        logger.debug("Connected to MCP server: %s", self.session)
        if self.load_tools_flag:
            await self.load_tools()
        if self.load_prompts_flag:
            await self.load_prompts()

        if logger.level != logging.NOTSET:
            try:
                await self.session.set_logging_level(
                    next(level for level, value in LOG_LEVEL_MAPPING.items() if value == logger.level)
                )
            except Exception:

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Ensure the MCP server and the mcp client library speak the same protocol version (upgrade/downgrade one side).
2. Increase request_timeout if the server is slow to initialize.
3. Run the server with verbose logging and confirm it completes its own initialize handshake with a known-good client (e.g. the mcp inspector).
4. Inspect the chained __cause__ for the protocol or timeout error.

Example fix

# before
plugin = MCPStdioPlugin(name="x", command="...", request_timeout=1)

# after
plugin = MCPStdioPlugin(name="x", command="...", request_timeout=30)

# smoke-test the server with a known-good MCP client (e.g. mcp inspector) before wiring SK
# and size request_timeout to the server's init latency
recommended_timeout = max(30, estimated_server_startup_seconds * 2)

def timeout_is_reasonable(request_timeout: int | None) -> bool:
    return request_timeout is None or request_timeout >= 10

from semantic_kernel.exceptions.kernel_exceptions import KernelPluginInvalidConfigurationError

try:
    async with MCPStdioPlugin(..., request_timeout=30) as plugin:
        ...
except KernelPluginInvalidConfigurationError as ex:
    if "Failed to initialize session" in str(ex):
        log.error("handshake failed: %r", ex.__cause__)
        # align client/server protocol versions, raise timeout, or check server logs

When it happens

Trigger: Server and client use incompatible MCP protocol versions; the server crashed or returned an error during initialize; the server timed out mid-handshake; request_timeout too small for a slow server. Originates at mcp.py:348-354.

Common situations: MCP server built against an older/newer protocol version than the client library; server requires auth not provided; slow-to-start servers hitting the default timeout; server throwing during capability advertisement; proxy stripping headers.

Related errors

• Failed to connect to the MCP server. Please check your confi
• Failed to create a session. Please check your configuration.
• Failed to enter context manager.
• MCP server not connected, please call connect() before using
• Tools are not loaded for this server, please set load_tools=

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