Loading today’s stories
Build1 distinct publisher2 min readUpdated
An empty MCP tool list is a successful response, and the bug is on the server side
When a client shows no tools, the handshake usually worked and tools/list returned a valid answer. Four of the six causes in one field writeup sit in what the server declared.
The Engineer · Build desk
What happened
- In the no-tools state the transport connected, the initialize handshake completed and parsed, and the client asked the server what it can do; the answer was 'nothing' or close to it. The handshake is healthy; the tool inventory is empty or unreadable.
- When a client shows no tools it has almost always received a perfectly valid tools/list response, one whose tools array is empty or whose entries the client discarded.
- Every no-tools case falls into one of two halves: the server genuinely advertised zero tools, or the server advertised tools and the client dropped them; telling which pile you are in is most of the work.
- The single most common cause is that the server never declared the tools capability in the initialize result; a spec-compliant client that does not see capabilities.tools may never call tools/list at all.
- The giveaway for a missing tools capability is that the initialize response parses fine but its capabilities object is missing tools entirely.
Compiled by The EngineerSomething wrong?How this is made
Why it matters
Two piles, and most of the work is knowing which one you are standing in: either the server genuinely advertised zero tools, or it advertised them and the client discarded the entries [3]. Ordinary triage misfires here because the failures engineers are trained on come with a pointer attached. A refused connection or a 401 tells you where to look [13]. This one does not, and it is not the same bug as a server that never finishes initialize, nor a server sitting behind auth [12].
Count the causes the dev.to writeup enumerates and the asymmetry is hard to miss. Six named root causes, and four of them originate in something the server declared or failed to declare: the missing capability, conditional registration that registered nothing, malformed inputSchema entries, and tools loaded after initialize with no change notification [1]. The remaining two, pagination and protocol-version negotiation, are the ones where client behaviour can be the deciding factor [8][9].
Pagination is the case worth singling out, because it is the one that leaves evidence sitting in plain sight. tools/list supports cursor pagination, so a server can return an empty first page carrying a nextCursor, or a client can request one page and stop reading [8]. The raw response contains the cursor. Nobody looks at the raw response, because the palette already told them the answer.
That is the shape of the whole problem. The empty answer is a 200, and nothing in the transport or the protocol is broken [14]. Restarting the process is almost never the fix, and the fault is rarely on the client [11]. What is broken is the content of a correct message, and the content of a correct message is exactly what a green connection indicator is designed not to inspect.
The malformed-schema case is the most quietly expensive of the four. A strict client can filter a tool whose inputSchema is not a valid JSON Schema object rather than render it as broken, so advertising five tools with three bad schemas can surface two, or none [7]. No error is returned to the server author. A schema that validated yesterday and does not today removes a tool from every agent that depends on it, and the only symptom is absence.
An MCP server can therefore be running, reachable, protocol-correct and honest, and still inform every client it has nothing to offer [1]. The client is not confused. It asked, or it was told not to ask, and it reported the answer it got [2][4].
Topics and entities
Follow any of these and your For You feed starts watching them — no settings page required.
Topics
Loading related stories