Writing an MCP Client: Discovering and Calling Tools Inside Your Own Agent Loop, Multi-Server Aggregation and Name Collisions
Switch to the client side: hand-write a client that discovers tools, translates them into a shape the model can understand, and feeds results back into the loop, then handle name collisions and failures when aggregating multiple servers.
Today's Goals
- Hand-write a stdio client that completes discovery, invocation, and error handling
- Translate MCP tool definitions into a model API's tool parameters, and point out where the two sides' names differ
- Design a naming-prefix and degradation strategy for aggregating multiple servers, so one server going down doesn't take the whole loop with it
For four days you wrote servers: registering tools, exposing resources, moving to the public internet, adding authorization. Today you move to the other side of the table. That order is deliberate — only after implementing everything a server can return do you know how many situations a client must catch. Come back and tick off the three goals above.
Plain-Language Walkthrough
What a client actually does
First, dispel a misconception: many people think an MCP client is a forwarder, handing the model's words to the server verbatim and the server's words back verbatim. Write one and you find the forwarding part is a few dozen lines and everything else is boundaries.
Back to the universal adapter metaphor. The server is the appliance, the protocol is the plug standard, and the client is the protected socket panel on your wall: it recognizes plugs, it limits current, and when one appliance starts smoking it trips only its own circuit rather than blacking out the building.
Concretely, three boundaries.
The first is the boundary of shape. An MCP tool definition and a model API's tool parameters are not the same thing. The field names differ, the naming rules differ, and what they can express differs. A translation has to sit in between, and a translation is always lossy — you need to know where.
The second is the boundary of naming. One host connected to five servers at once is normal, and the spec guarantees tool name uniqueness only within a single server. Two servers each having a search is inevitable, not an accident. Who disambiguates? Only the client can.
The third is the boundary of failure. A server runs in somebody else's process on somebody else's machine. It will time out, it will crash, a user will delete it by accident. Those failures must be held outside the agent loop — one server going down should at worst mean a few fewer tools, not a failed conversational turn.
Those three boundaries are exactly the three pieces of code to write today.
Interview questions
Your client is connected to five MCP servers and two of them expose a tool called search. How do you merge them into one tool list for the model, and why can't you just prefix with the server's name?你的客户端同时连了五个 MCP 服务端,其中两个都有一个叫 search 的工具。合并成一张工具表给模型时,重名该怎么处理?为什么不能直接拿服务端名做前缀?
Common in ChinaCommon overseasIntermediate#client#tool-naming🔒 Unlock this chapter to see the answer keys.
One of your MCP servers times out in production. How should your agent loop react?线上一个 MCP 服务端超时了。你的 Agent 循环应该怎么反应?
Common in ChinaCommon overseasIntermediate#client#reliability🔒 Unlock this chapter to see the answer keys.
When translating an MCP tool definition into a model API's tool parameters, what is most easily lost, and what goes wrong when it is?把 MCP 的工具定义翻译成模型 API 的工具参数时,最容易丢掉的是什么?丢了会怎样?
Common in ChinaCommon overseasDeep dive#client#tool-schema🔒 Unlock this chapter to see the answer keys.
