microsoft/semantic-kernel · error · KernelPluginInvalidConfigurationError

Failed to create a session. Please check your configuration.

Error message

Failed to create a session. Please check your configuration.

What it means

Thrown by MCPPluginBase._inner_connect (mcp.py:345) as a KernelPluginInvalidConfigurationError when ClientSession(...) construction fails after the transport was obtained. This is distinct from transport creation (1350) and from the initialize handshake (1352): the session object itself could not be created from the read/write streams.

Source

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

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

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Inspect the chained __cause__ for the exact ClientSession error.
2. Pin compatible versions of the mcp and semantic-kernel packages.
3. If supplying custom message_handler/logging_callback/sampling_callback, match the expected callable signatures exactly.
4. Reproduce with a minimal plugin config to isolate whether a callback or the transport is at fault.

Example fix

# before (callback with wrong signature)
plugin = MCPStdioPlugin(..., logging_callback=lambda level, data: None)

# after (match the expected (level, data, logger) shape per mcp ClientSession)
plugin = MCPStdioPlugin(..., logging_callback=lambda level, data, logger=None: logger.info(data))

# validate callback signatures match mcp ClientSession expectations before passing
import inspect

def callbacks_well_formed(message_handler, logging_callback, sampling_callback) -> bool:
    for cb in (message_handler, logging_callback, sampling_callback):
        if cb is not None and not callable(cb):
            return False
    return True

def is_callable_or_none(cb) -> bool:
    return cb is None or callable(cb)

from semantic_kernel.exceptions.kernel_exceptions import KernelPluginInvalidConfigurationError

try:
    async with plugin:
        ...
except KernelPluginInvalidConfigurationError as ex:
    if "Failed to create a session" in str(ex):
        log.error("session creation failed: %r", ex.__cause__)
        # simplify callbacks and retry, or pin compatible mcp version

When it happens

Trigger: ClientSession instantiation raises, e.g. incompatible transport stream shapes, a programming error in callbacks (message_handler/logging_callback/sampling_callback signatures), or an internal mcp ClientSession failure at mcp.py:333-347.

Common situations: Passing custom callbacks with wrong signatures; mcp library version mismatch where ClientSession expects different streams; a subclass overriding get_mcp_client returning malformed transport tuples; corrupted state after a prior failed connect.

Related errors

• Failed to connect to the MCP server. Please check your confi
• Failed to initialize session. Please check your configuratio
• MCP server not connected, please call connect() before using
• Failed to enter context manager.
• 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/783f7e11e4190783. Report an issue: GitHub.