langchain-ai/deepagents · error · ValueError

Couldn't find an MCP server named '{server_name}', expected

Error message

Couldn't find an MCP server named '{server_name}', expected one of {sorted(self._connections)}

What it means

get_session/_create_entry raises ValueError when the requested server_name has no entry in the manager's configured connections, listing the valid names.

Source

Thrown at libs/code/deepagents_code/mcp_tools.py:788

        Returns:
            A cached session entry containing the live session and close stack.

        Raises:
            RuntimeError: If the manager has already been cleaned up.
            ValueError: If `server_name` is not configured in the manager.
        """
        if self._closed:
            msg = "Cannot create an MCP session after cleanup"
            raise RuntimeError(msg)

        try:
            connection = self._connections[server_name]
        except KeyError as exc:
            msg = (
                f"Couldn't find an MCP server named '{server_name}', "
                f"expected one of {sorted(self._connections)}"
            )
            raise ValueError(msg) from exc

        exit_stack = AsyncExitStack()
        try:
            session = await exit_stack.enter_async_context(
                _create_mcp_session(connection, server_name=server_name)
            )
            await session.initialize()
        except BaseException:
            # Close the partially entered stack in *this* task before
            # propagating. `create_session` enters an AnyIO task group whose
            # cancel scope must be exited by the task that entered it; deferring
            # teardown to async-generator finalization on another task raises
            # "Attempted to exit cancel scope in a different task than it was
            # entered in". Catch `BaseException` (not just `Exception`) so a
            # `CancelledError` — e.g. from a crashed Streamable HTTP transport
            # task group cancelling `session.initialize()` — also triggers the
            # in-task teardown below instead of abandoning the session. The bare
            # `raise` re-raises the original exception unchanged, so cancellation

View on GitHub (pinned to a1af029e6e)

Solutions

Use a name from the 'expected one of' list in the message
Reconfigure the manager to include the missing server
Verify the server survived config validation (it may have been dropped as invalid)

Example fix

// before
await manager.get_session('Filesystem')  # not configured
// after
await manager.get_session('filesystem')  # matches configured key

Defensive patterns

Strategy: validation

Validate before calling

configured = set(manager._connections)  # or track the config keys you passed
if server_name not in configured:
    raise KeyError(f'{server_name!r} not configured; known: {sorted(configured)}')

Try / catch

try:
    session = await manager.get_session(server_name)
except ValueError as e:
    log.error('unknown MCP server %r; check config keys', server_name)
    raise

Prevention

Keep server name constants/shared config keys instead of string literals
Re-check the MCP config after edits; invalid servers may be dropped at validation time
Log the configured server list at startup for quick comparison

When it happens

Trigger: Calling get_session('typo-name') or a name present in an MCP config file but never configured on the manager (e.g. filtered out by validation).

Common situations: Typo or case mismatch in the server name; server dropped by _drop_invalid_mcp_config_servers before configuration; config file edited after the manager was configured.

Related errors

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/e7802a3e8075b0f5. Report an issue: GitHub.