langchain-ai/deepagents · error · RuntimeError

MCP server '{server_name}': configured command not found on

Error message

MCP server '{server_name}': configured command not found on PATH. Install it or check your MCP config.

What it means

For stdio MCP servers, `_check_stdio_server` resolves the configured `command` with `shutil.which`. If the executable is not found on the system PATH it raises this RuntimeError telling you to install the command or fix the config. The config is structurally valid; the binary simply isn't available in the current environment.

Source

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

    """Verify that a stdio server's command exists on PATH.

    Args:
        server_name: Server name for error messages.
        server_config: Validated server config.

    Raises:
        RuntimeError: If the command is missing or not found on PATH.
    """
    command = server_config.get("command")
    if command is None:
        msg = f"MCP server '{server_name}': missing 'command' in config."
        raise RuntimeError(msg)
    if shutil.which(command) is None:
        msg = (
            f"MCP server '{server_name}': configured command not found on PATH. "
            "Install it or check your MCP config."
        )
        raise RuntimeError(msg)


async def _check_remote_server(server_name: str, server_config: dict[str, Any]) -> None:
    """Check network connectivity to a remote MCP server URL.

    Args:
        server_name: Server name for error messages.
        server_config: Validated remote server config.

    Raises:
        RuntimeError: If the URL is missing, unreachable, or returns 5xx.
    """
    import httpx

    url = server_config.get("url")
    if url is None:
        msg = f"MCP server '{server_name}': missing 'url' in config."
        raise RuntimeError(msg)

View on GitHub (pinned to a1af029e6e)

Solutions

1. Install the command (e.g. `npm install -g <pkg>` for npx-based servers, `pip install`/`uv tool install` for uvx-based ones) and confirm with `which <command>`.
2. Use an absolute path to the executable in 'command' if it lives outside PATH, e.g. "/home/me/.local/bin/mcp-server-fs".
3. Fix PATH for the environment running the agent (export PATH=... in the shell, systemd unit, or container image) so the binary resolves.
4. If the server moved/renamed, update the 'command' value in the MCP config to the current executable name.

Example fix

// before
{"mcpServers": {"fs": {"command": "mcp-server-fs", "args": ["/tmp"]}}}
// after (absolute path, or install the binary first)
{"mcpServers": {"fs": {"command": "/home/me/.local/bin/mcp-server-fs", "args": ["/tmp"]}}}

import shutil
for name, server in cfg["mcpServers"].items():
    cmd = server.get("command")
    if cmd and shutil.which(cmd) is None:
        raise SystemExit(f"'{name}': command '{cmd}' not on PATH — install it")

def command_available(server: dict) -> bool:
    import shutil
    cmd = server.get("command")
    return isinstance(cmd, str) and shutil.which(cmd) is not None

try:
    check_mcp_servers(cfg)
except RuntimeError as e:
    if "not found on PATH" in str(e):
        print(f"install the tool or fix PATH: {e}")
    else:
        raise

When it happens

Trigger: Config command like "mcp-server-fs", "npx", or "uvx" that isn't installed or isn't on PATH when the check runs: binary never installed, run inside a container/venv lacking the tool, or a Windows-only command on Linux.

Common situations: Fresh machine or CI container missing Node/npx or uvx; tool installed via pipx/cargo into ~/.local/bin not on PATH in the shell running dcode; command renamed between versions; using a package-internal entry point without installing the package.

Related errors

• Server '{server_name}' 'env' must be a dictionary
• Could not import Deep Agents Code dependencies or locate dco
• External editor executable or temporary file was not found
• Server '{server_name}' uses {transport!r} transport; OAuth l
• {prefix}.args must be a list, got {type(args).__name__}

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