An MCP server fails during initialization from a LangChain client
Unsupported protocol versionShort 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.
Fix it fast
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/null2Match what you see, then jump to its fix
- 1
The 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
The 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
An error reply to initialize: Unsupported protocol version, code -32602, with the supported versions in dataClient and server disagree on the protocol versionFix - 4
The adapter rejects the argument before any handshake happensThe target passed to the adapter is the wrong kindFix
- 1
What does the error look like?
Unsupported protocol versionJSON-RPC error -32602 on the initialize requestThe 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.py2Fix
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/nullConfirmed by modelcontextprotocol.io
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_KEY2Fix
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
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 langchain3Verify
Initialize again; the reply now carries a protocolVersion both sides accept.
python -m pip list | grep -i "mcp\|langchain"Confirmed by modelcontextprotocol.io
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
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:
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
AI
Azure OpenAI says the API deployment for this resource does not exist
The API deployment for this resource does not exist
Azure OpenAI does not take a model name in the model field.
2 causes, each with a fixAI
Azure OpenAI fails with an SSL certificate verification error
httpx.ConnectError: [SSL: CERTIFICATE_VERIFY_FAILED]
The client checks the endpoint's certificate against its CA bundle, which is certifi by default.
2 causes, each with a fixAI
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 fixAI
Gemini API returns 429 RESOURCE_EXHAUSTED on the free tier
429 RESOURCE_EXHAUSTED
Gemini limits are applied per Google Cloud project, not per API key, so a new key in the same project does not reset anything.
3 causes, each with a fixAI
ChatPromptTemplate is missing the variable agent_scratchpad
Expected: ['agent_scratchpad', 'input']
A tool-calling agent keeps its tool calls and tool results in a prompt slot named agent_scratchpad.
2 causes, each with a fixAI
LangChain no longer exports AgentExecutor from langchain.agents
ImportError: cannot import name 'AgentExecutor' from 'langchain.agents'
LangChain v1 moved legacy classes into a separate package called langchain-classic, and AgentExecutor lives there now.
2 causes, each with a fix