What AI agents actually do with your MCP server

说明与用途

MCP 服务器看似健康，但代理因缺失工具、错误参数、描述模糊、循环调用和隐藏的响应大小而遇到问题。mcpspan 分析工具可帮助识别并修复这些问题，提升代理交互。

问题

MCP servers appear healthy but agents struggle due to tool mismatches, argument validation failures, ambiguous tool descriptions, looping calls, and hidden response size issues.

结果

The server’s agent interactions improved: fewer missing tool errors, reduced argument validation failures, clearer tool usage, fewer loops, and controlled response sizes, leading to better agent performance and more accurate metrics.

工作流

• 1. Instrument the MCP server with mcpspan to capture tool usage and metrics.
• 2. Analyze logs to find tool names requested that do not exist and map them to closest existing names.
• 3. Inspect argument validation failures to determine if they stem from schema mismatches.
• 4. Refine tool descriptions to match expected input types (e.g., list vs. count).
• 5. Detect and mitigate looping calls by improving response messages with actionable guidance.
• 6. Monitor response sizes and enforce limits or provide summaries to avoid token waste.
• 7. Iterate on tool definitions and descriptions based on observed metrics.

证据

Agents guess tool names. Some guesses are near misses: searchFlights when the tool is search_flights, seatMap instead of seat_map. Others are a tool the agent assumed should exist, like get_flight_price.

来源

When an agent sends arguments that don't match the input schema, the MCP SDK rejects them before your handler runs and sends the validation error back to the model as a normal result.

来源

book_flight took passengers, described as "the passengers". Agents read that as a count and sent 2. The schema wanted a list of names, so the SDK refused the call.

来源

An agent tries check_in, gets "Check-in opens 24 hours before departure", and calls check_in again with exactly the same arguments.

来源

A tool that usually answers with 6 kB and sometimes with 650 kB looks fine on every latency chart, because it's fast. But that answer lands in the agent's context window, crowds out everything else, and costs tokens on every following turn.

来源

I built [mcpspan](https://github.com/mcpspan/mcpspan) for this: self-hosted analytics for MCP servers, MIT licensed.

来源