Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
AI and LLM integration

An MCP server fails during initialization from a LangChain client

ErrorUnsupported protocol version

Short answer

The MCP handshake is fixed: the client sends initialize, the server answers, the client sends initialized. Failures come from whatever breaks that exchange. A stdio server printing to stdout, a launch path or environment the client cannot resolve, a protocol version mismatch, or a transport target of the wrong type are the four confirmed causes.

  • Applies to MCP specification 2025-06-18, langchain 1.4 with langchain.mcp, Python 3.12
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Start the server command on its own, outside LangChain, with an absolute path. If it prints anything that is not protocol JSON to stdout, or exits at once, you have found the problem.

    python /absolute/path/to/server.py < /dev/null
  2. 2Match what you see, then jump to its fix

    1. 1The connection dies at start, and a plain text line shows up when you run the server by handThe stdio server writes logs or print() output to stdoutFix
    2. 2The server starts fine in your shell but never initializes when launched by the clientThe client cannot find the command, the files or the environmentFix
    3. 3An error reply to initialize: Unsupported protocol version, code -32602, with the supported versions in dataClient and server disagree on the protocol versionFix
    4. 4The adapter rejects the argument before any handshake happensThe target passed to the adapter is the wrong kindFix

What does the error look like?

  • Unsupported protocol version
  • JSON-RPC error -32602 on the initialize request
  • The MCP connection closes or times out before any tools are listed

Cause 1 of 4

The stdio server writes logs or print() output to stdout

1Check

A stdio MCP server talks to the client over stdout. MCP's debugging guide says local servers should not log to stdout because it interferes with the protocol; stderr is captured by the host instead.

grep -n "print(" /absolute/path/to/server.py

2Fix

Remove print() calls and send all logging to stderr.

import logging, sys

logging.basicConfig(stream=sys.stderr, level=logging.INFO)
logger = logging.getLogger(__name__)
logger.info("server starting")

3Verify

Run the server by hand again: stdout stays silent until a client speaks.

python /absolute/path/to/server.py < /dev/null

Confirmed by modelcontextprotocol.io

Did this fix it?

Cause 2 of 4

The client cannot find the command, the files or the environment

1Check

The debugging guide says a client may launch a stdio server with an undefined working directory, and that servers inherit only a limited set of environment variables. Relative paths and a missing API key both fail only under the client.

which python
env | grep -i MY_API_KEY

2Fix

Use absolute paths for the command and every file it reads, and pass required variables in the server's env setting.

{
  "mcpServers": {
    "reports": {
      "command": "/usr/bin/python3",
      "args": ["/absolute/path/to/server.py"],
      "env": { "MYAPP_API_KEY": "set-me" }
    }
  }
}

3Verify

Restart the client and list the server's tools.

echo "restart the client, then list tools"

Confirmed by modelcontextprotocol.io

Did this fix it?

Cause 3 of 4

Client and server disagree on the protocol version

1Check

In the initialize request the client sends a version. The server must answer with the same one if it supports it, or with another it supports. If the client does not support the answer it should disconnect.

python -m pip list | grep -i "mcp\|langchain"

2Fix

Upgrade the older side so both speak a common version; check which side is older with the pip list above.

python -m pip install -U mcp langchain

3Verify

Initialize again; the reply now carries a protocolVersion both sides accept.

python -m pip list | grep -i "mcp\|langchain"

Confirmed by modelcontextprotocol.io

Did this fix it?

Cause 4 of 4

The target passed to the adapter is the wrong kind

1Check

LangChain's langchain.mcp adapter treats a URL string as Streamable HTTP, a Path to a script as stdio (one subprocess per adapter), and a FastMCP instance as in-process. A string must be an http or https URL, so a script path given as a plain string is rejected.

grep -n "MCPAdapter(" -r --include='*.py' .

2Fix

Give a Path for a local script, or an http(s) URL for a server that is already running.

from pathlib import Path
from langchain.mcp import MCPAdapter

async with MCPAdapter(Path("/absolute/path/to/server.py")) as adapter:
    tools = await adapter.list_tools()

3Verify

list_tools() returns the server's tools.

print([t.name for t in tools])

Confirmed by docs.langchain.com

Did this fix it?

How do I stop it coming back?

  • Treat stdout as the protocol channel: log to stderr only.
  • Use absolute paths and an explicit env block for every stdio server.
  • Pin and upgrade the MCP SDK and LangChain together.
  • Test a new server by itself before wiring it into an agent.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

AI

LangChain says it could not import the chromadb package

ImportError: Could not import chromadb python package. Please install it with `pip install chromadb`.

The message comes from LangChain's old Chroma class, which cannot import chromadb in the Python that runs your code.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.