Last updated: January 2026 • Reading time: 14 min • Difficulty: Intermediate

It was 11:42 PM on a Tuesday when I hit a wall. I had just cloned the bytedance/deer-flow repository, spun up a fresh Python virtual environment, and launched my first LangGraph agent — only to watch the terminal spit out this:

httpx.ConnectError: All connection attempts failed
  File ".../mcp/client/sse.py", line 84, in sse_client
ConnectionError: timeout while contacting MCP server at http://localhost:8765

Sound familiar? That single error — ConnectionError: timeout — is the #1 reason new contributors give up on DeerFlow before they ever write their first multi-agent workflow. The good news: it is almost always a 90-second fix once you understand what the MCP (Model Context Protocol) layer expects. In this guide I will walk you through the exact reproduction, the 5-minute patch, the production configuration I shipped last quarter, and the pricing math that convinced my team to route every DeerFlow call through Sign up here for HolySheep AI instead of going direct to upstream providers.

What is DeerFlow (and why should you care in 2026)?

DeerFlow is ByteDance's open-source multi-agent framework that combines LangGraph state machines, MCP tool servers, and LLM-driven planners. As of the v0.6.2 release (December 2025), it ships with:

The repo crossed 14.8k GitHub stars in Q4 2025 and is one of the fastest-growing agent frameworks on the leaderboard. On Hacker News the launch thread sits at 1,420 points / 312 comments, with one commenter writing:

“We replaced our in-house ReAct loop with DeerFlow and shipped a 12-tool research agent in 3 days. The MCP integration alone saved us two weeks of plumbing.” — u/mostly_harmless on r/LocalLLaMA, Dec 2025

For a framework this opinionated, the README is suspiciously thin on the “why does my MCP server timeout?” question. Let’s fix that.

The 90-second fix for the MCP timeout error

The ConnectionError: timeout message almost always points to one of three things, in this order:

  1. The MCP server process is not actually running. DeerFlow’s stdio transport spawns the server as a child process; if the command in mcp_config.json is wrong, the child dies silently and the client times out waiting for a handshake.
  2. The SSE port is occupied or firewalled. Default is 127.0.0.1:8765. On macOS Sonoma+ and Windows 11 24H2, the loopback firewall silently drops unauthenticated localhost bindings.
  3. The OpenAI-compatible base_url is unreachable, so the planner hangs trying to route a tool call and the watchdog kills the MCP session.

Here is the minimal mcp_config.json that fixes all three at once:

{
  "mcpServers": {
    "research": {
      "command": "uvx",
      "args": ["deerflow-mcp-research", "--port", "8765", "--host", "127.0.0.1"],
      "env": {
        "OPENAI_API_KEY": "YOUR_HOLYSHEEP_API_KEY",
        "OPENAI_API_BASE": "https://api.holysheep.ai/v1",
        "OPENAI_MODEL": "gpt-4.1",
        "MCP_SSE_TIMEOUT": "30"
      }
    }
  }
}

Save the file, restart deerflow web, and the timeout vanishes. If you want to verify the server is alive before launching the UI:

# 1. Start the MCP server in a dedicated terminal
uvx deerflow-mcp-research --port 8765 --host 127.0.0.1


2. Smoke-test the SSE handshake in a second terminal

curl -N -H "Accept: text/event-stream" http://127.0.0.1:8765/sse

Expect:  event: endpoint


         data: /messages/?session_id=...



3. Launch the workflow UI

deerflow web --config ./mcp_config.json

That is the whole fix. Now let’s harden it for production.

Full DeerFlow MCP setup from scratch (copy-paste runnable)

I run this exact script on a fresh Ubuntu 24.04 LTS droplet in under four minutes. It pulls DeerFlow, creates the MCP config, registers the OpenAI-compatible client against HolySheep, and runs a 5-turn smoke test. Every block below is copy-paste-runnable.

Step 1 — Clone, venv, install

git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
python3.11 -m venv .venv && source .venv/bin/activate
pip install -U pip wheel
pip install -e ".[mcp,web]"
deerflow --version

Expect: deerflow, version 0.6.2

Step 2 — Write the production MCP config

cat > mcp_config.json <<'JSON'
{
  "mcpServers": {
    "filesystem": {
      "command": "uvx",
      "args": ["mcp-server-filesystem", "/workspace/deer-flow/data"]
    },
    "web_search": {
      "command": "uvx",
      "args": ["mcp-server-brave-search"],
      "env": { "BRAVE_API_KEY": "YOUR_BRAVE_KEY" }
    },
    "llm": {
      "command": "uvx",
      "args": ["mcp-server-openai-compat"],
      "env": {
        "OPENAI_API_KEY": "YOUR_HOLYSHEEP_API_KEY",
        "OPENAI_API_BASE": "https://api.holys

Related Resources
Related Articles