Claude Code: a slow MCP server misses your first prompt

Why does Claude Code say it has no tool for something when your MCP server is configured? If you type your first prompt while the server is still connecting, Claude doesn’t get the server. I drove 57 interactive Claude Code sessions through tmux with a notes server that took 0 to 40 seconds to connect. With the server 3 seconds or slower and the prompt typed as soon as the input box appeared, the first prompt used the server in 2 of 45 runs, with alwaysLoad set or not. Claude searched for the tool, found unrelated ones, and said it had no data. Headless claude -p waited for the same 15-second server and answered right in 4 of 4 (8 of 8 with the undelayed server).

This is the sixth post on agent memory and MCP. The alwaysLoad post tested slow servers only with -p, where Claude Code waits for them, and ended with “Interactive sessions connect in the background, so the startup difference may matter there; I didn’t test that.” This is that test.

Why are my MCP tools missing on the first prompt?

Claude Code draws its input box before it starts your MCP servers. In all 57 sessions the box appeared a median 1.0 s after launch, and Claude Code spawned the server a median 1.6 s after launch. If you type right away, the first API request goes out 0.07 to 0.49 s after you press Enter, whatever the server is doing.

The server here is the BM25 notes search from the 97-line server post, with a STARTUP_DELAY_MS switch that holds back the stdio connection. The question has one answer, and it is only in the notes: “What generation speed in tokens per second did Gemma 4 E2B reach on the 2-core laptop?” (7.1). A turn counts as right when the answer says 7.1.

Interactive session, prompt typed as soon as the input box appeared	Runs	First prompt used the tool	“Please try again” used it
Server connects in ~1.5 s (no delay)	6	6	n/a
Server delayed 3 s	3	1	2 of 2
Server delayed 5 s	6	1	5 of 5
Server delayed 15 s (Sonnet, Haiku, Opus)	10	0	9 of 10
Server delayed 15 s, with one of five env settings	20	0	16 of 20
Server delayed 40 s	6	0	0 of 6
Server delayed 15 s, prompt typed 20 s after launch	2	2	n/a

The loading mode made no difference. Each delay ran with the tools deferred (the default), with the search tool marked _meta["anthropic/alwaysLoad"] by the server, and with "alwaysLoad": true on the server’s config entry. The one 5 s hit was per-tool and the one 3 s hit was per-server, one run each, so I read them as timing luck rather than a pattern.

Waiting works. With the same 15 s server, a prompt typed 20 s after launch used the tool 2 of 2 times.

How I tested it

bench/run.py starts claude (the full terminal UI, not -p) in a detached tmux pane, polls the pane until the input box is drawn, types the question, and waits for the turn to end. If the notes tool wasn’t called, it sends “Please try again.” as a second turn. Each session gets its own --session-id, so the script can read Claude Code’s own transcript from ~/.claude/projects/:

• api-request and api-request-shape entries give the time of every API request and the tool list it carried.
• deferred_tools_delta attachments name the servers still pending ("pendingMcpServers": ["notes"]) and when the notes tools were added.
• Tool calls, ToolSearch results and answers.

The server writes its own log with wall-clock times for process start, connection and every tool call. Each session ran with only this server (--strict-mcp-config), --setting-sources project, CLAUDE.md files and auto-memory off, and Bash, Read, Grep and Glob disallowed. That makes the server the only way to the answer. In a normal session Claude could grep your files instead, which I didn’t measure.

One tmux gotcha cost me the first smoke run: an Enter sent in the same burst as the typed text is taken as part of a paste and dropped. The script now waits 0.4 s, presses Enter, and repeats until the prompt shows up in the transcript.

What does Claude do while the server is still connecting?

It knows the server is coming. In 44 of 45 slow runs, the first request carried a deferred_tools_delta with "pendingMcpServers": ["notes"], and some answers start with “The still-connecting notes server might have this, so I’ll search there.” Then it searches, and that’s where it goes wrong:

❯ What generation speed in tokens per second did Gemma 4 E2B reach on the 2-core laptop? Answer in one or two
  sentences.

● I can't search the repo directly with the tools I have loaded. The still-connecting notes server might have this, so
  I'll search there.

● I can't tell you, because I don't have the figure. The search for the notes server's tools returned nothing relevant.
  The tools I can use here can't read or search the repo's files, so I couldn't find the Gemma 4 E2B benchmark post.

  If you paste the relevant section, or the path to the post, I'll pull out the tokens-per-second number. I won't guess
  a speed.

The MCP docs say: “If your request needs tools from a server that is still connecting in the background, Claude waits for that server before continuing”, and with tool search on, “the wait happens inside the ToolSearch call.” I timed every ToolSearch call made before the server connected:

ToolSearch call while the server was pending	Calls	Median time	Range
Keyword search that matched other tools (“notes search”, “notes gemma”)	75	25 ms	9 ms to 3.5 s
Keyword search with no match (“gemma”)	1	2,524 ms
select: of tool names that didn’t exist yet	35	5,034 ms	17 ms to 5.1 s

The wait exists, but only when the search comes back empty. Then ToolSearch holds until the server connects or about 5 seconds pass. If the server still isn’t there, the result says so: 22 of those empty results read “Some MCP servers are still connecting: notes.” and told Claude to try searching again. Claude’s usual searches weren’t empty, because keyword search matched Claude Code’s plan-mode tools and a browser tool. So they returned in 25 ms with three unrelated tools, and Claude concluded there was no notes tool. The single bare “gemma” search matched nothing, waited 2.5 s until the server connected, and that run is the 5 s success in the table.

Most select: calls were Claude asking for Read, Grep, Glob and Bash, which this test blocks. They waited the full 5 s and found nothing, but sometimes the server connected during that wait. Claude Code then lists the new tools on the next request in the same turn, as the docs say, and Claude used them. That is why “Please try again” worked 32 of 37 times for servers under 30 s. In 27 of the 37 retries the server still hadn’t connected when the retry was sent, and 22 of those still ended right, because the turn lasted long enough to catch the server.

The good news is that Claude never guessed. All 43 misses said they had no data and asked for the file or a retry. None gave a number.

Do alwaysLoad or the startup wait settings help?

The docs say both should. The alwaysLoad section: “Setting alwaysLoad: true also makes startup wait for the server’s tools, capped at the standard 5-second connect timeout, since they must be present when the first prompt is built.” The environment variable reference says MCP_CONNECTION_NONBLOCKING=0 makes “Claude Code wait for servers to connect before the first query”, with MCP_CONNECT_TIMEOUT_MS (default 5000) as the deadline.

With a 15 s server, two runs each:

Setting	First prompt used the tool	Retry used it
MCP_CONNECTION_NONBLOCKING=0, deferred and per-server	0 of 4	2 of 4
MCP_CONNECTION_NONBLOCKING=0 + MCP_CONNECT_TIMEOUT_MS=30000	0 of 4	3 of 4
MCP_CONNECTION_NONBLOCKING=false	0 of 4	4 of 4
CLAUDE_CODE_MCP_STARTUP_WAIT_MS=30000	0 of 4	4 of 4
CLAUDE_CODE_MCP_ALWAYS_LOAD_JOIN_BEFORE_INPUT=1, per-tool and per-server	0 of 4	3 of 4

None of them held the first turn. A 5-second cap can’t rescue a 15-second server, but no wait happened at all. The first request still left 0.07 to 0.49 s after the prompt, and with the 3 s server, inside the 5 s cap, per-server alwaysLoad still missed once in two runs. CLAUDE_CODE_MCP_STARTUP_WAIT_MS is documented for non-interactive sessions only, so it isn’t expected to work here. CLAUDE_CODE_MCP_ALWAYS_LOAD_JOIN_BEFORE_INPUT isn’t documented; I found the name in the Claude Code binary and tried it because of what it says. Either the documented waits don’t apply to the interactive input path in 2.1.316, or they need something my setup didn’t have. I’m reporting what I measured, not the code path behind it.

Is claude -p different?

Yes. The same question and server with claude -p, two runs per loading mode (deferred and per-tool alwaysLoad):

claude -p	Runs	Used the tool and right	Server connected	Wall time
Server delayed 0 s	4	4	0.9 s	5.0 to 7.1 s
Server delayed 15 s	4	4	15.9 to 16.0 s	19.7 to 22.5 s
Server delayed 40 s	4	0	never	36.1 to 37.0 s

Headless mode waits for pending servers before the first turn, as the alwaysLoad post found, so a slow server only makes the run slower. Scripts and timers are safe. People typing at a terminal are not.

What about servers slower than 30 seconds?

They never arrive, in either mode. MCP_TIMEOUT defaults to 30 s, and at 30 s Claude Code marks the server failed ("errorCode": "CONNECT_TIMEOUT" in the transcript). Typing 45 s after launch didn’t help, and after a failure ToolSearch stopped waiting (17 ms for a select:). With MCP_TIMEOUT=60000, the same 40 s server was used on a prompt typed at 45 s, 2 of 2.

How to keep a slow MCP server from missing the first prompt

From these runs:

1. Make the server connect fast. Claude Code waits for the MCP handshake, not for your index. A server that finished its handshake at once was used 6 of 6 times. If you load a big index at startup, connecting first and loading afterwards should help, though I didn’t measure a server built that way.
2. As a user, wait or ask again. The terminal showed nothing about the pending server in any of 45 screen captures taken 2 s after sending. Run /mcp before your first prompt if the server is slow. If Claude says it has no tool, “try again” a few seconds later worked 32 of 37 times here.
3. Raise MCP_TIMEOUT for servers that take over 30 s, or they never connect in the session at all.
4. Use claude -p for anything scripted. It waited for the server every time.
5. Don’t count on alwaysLoad or MCP_CONNECTION_NONBLOCKING=0 to hold the first interactive turn in Claude Code 2.1.316. They didn’t here.

alwaysLoad is still worth setting for what the alwaysLoad post measured: once the server is connected, a tool loaded upfront gets called far more reliably than a deferred one with a vague name. It just doesn’t fix the startup race.

What broke and what I’d do differently

• I first tested the wrong spelling. My first batch set MCP_CONNECTION_NONBLOCKING=false. The docs say 0. I reran with 0 (and with a 30 s connect deadline): same result, 0 of 8.
• Blocking Bash and Read shapes the misses. Most of the 5-second select: waits were Claude asking for the blocked file tools. With them allowed, Claude would probably have grepped the folder instead, as it did in the 97-line server post when it was not told a server had failed, which is a different answer to the same race. Haiku also tried a Bash call once and was refused.
• Small samples per cell. Two runs per condition, one question, one small server, one machine. The direction was the same in every cell (2 hits in 45), but the 3 s and 5 s rows are where timing decides, and two runs can’t pin that down.
• One session never drew its input box within 60 s and is left out. Its row is in the repo with the error.

The harness, the server and every run are in the project folder. The interactive sessions used 5.2 million input tokens (mostly cache reads) and 44,000 output tokens on a subscription. The 12 headless runs cost USD 0.28 at API prices, by Claude Code’s own count.