---
title: How do you monitor MCP tool call failures across AI agents?
url: https://opencontroller.lyzr.com/blog/monitor-mcp-tool-call-failures
published: 2026-11-13
updated: 2026-11-13
author: Lyzr
---

# How do you monitor MCP tool call failures across AI agents?

**Log every MCP tool call with the same fields: agent, server, tool, argument hash, latency, outcome and error class. Treat the two kinds of MCP failure separately: JSON-RPC protocol errors, and tool results returned with `isError` set to true. Then alert per server on error rate, latency and new failure types, not on single failures.**

Teams that build agents on their own MCP servers often find the same pattern. The agent "kind of works", but some answers are wrong because a tool call failed quietly and the model carried on. MCP failures are easy to miss because many of them are not errors at the transport level. The model sees them, apologises, and tries something else. Nobody else does.

## What kinds of failure does MCP report?

The Model Context Protocol has two error channels for tools. Knowing which one fired tells you who should fix it.

| Failure type | How it appears | Typical causes | Who fixes it |
|---|---|---|---|
| Protocol error | JSON-RPC `error` object with a code, for example -32601 method not found or -32602 invalid params | Unknown tool name, malformed request, server crash | Server owner or client integration |
| Tool execution error | Normal result with `isError: true` and a text message | Downstream API down, permission denied, bad input, business rule rejected | Depends on the message |
| Transport failure | Timeout, connection reset, HTTP 401/403/5xx on Streamable HTTP | Network, authentication, server overloaded | Platform or server owner |
| Silent failure | Successful result with empty or wrong content | Bug in the tool, stale data, wrong defaults | Server owner, found by evals |

One detail matters for monitoring. Since the 2025-11-25 revision of the MCP specification, input validation errors (for example a wrong argument type or a date in the past) should be returned as tool execution errors with `isError: true`, not as protocol errors. The reason is that the model can read the message and fix its own call. That is good for agents, but it means a dashboard that only counts JSON-RPC errors will under-count failures.

## Which fields should you log for every tool call?

Use one schema across all agents and servers, so you can compare them.

1. **Agent ID and version** that made the call.
2. **Server ID** and server version from the registry, not just a URL.
3. **Tool name.**
4. **Argument hash** plus a redacted argument sample. The hash lets you group identical failing calls without storing sensitive data.
5. **Start time and latency** in milliseconds.
6. **Outcome:** success, tool error, protocol error, transport error.
7. **Error class:** your own normalised category, such as `auth`, `validation`, `downstream_unavailable`, `rate_limited`, `timeout`, `not_found`.
8. **JSON-RPC error code** where present.
9. **Retry count** and whether the agent eventually succeeded.
10. **Trace ID** linking the call to the agent run and the model calls around it.

Emit these as OpenTelemetry spans where you can. The OpenTelemetry GenAI semantic conventions include attributes for tool execution, which helps if you already send traces to a central backend. See [export AI agent traces with OpenTelemetry](/blog/export-ai-agent-traces-with-opentelemetry).

## How do you classify tool error messages?

`isError` results carry free text. Normalise them with simple rules first, and only add an LLM classifier for the long tail.

- Messages containing "unauthorized", "forbidden" or HTTP 401/403 map to `auth`.
- "Invalid", "must be", "expected" map to `validation`.
- HTTP 429 or "rate limit" map to `rate_limited`.
- HTTP 5xx or "unavailable" map to `downstream_unavailable`.

Review the unclassified bucket weekly. New categories usually point at a server change nobody announced. That is also why you should [review MCP server updates before use](/blog/review-mcp-server-updates-before-use).

## What alert thresholds make sense per MCP server?

Single failures are noise. Agents retry, and models recover from validation errors. Alert on patterns instead. Starting points to tune against your own baseline:

| Signal | Example threshold | Why |
|---|---|---|
| Error rate per server | Above 5% over 15 minutes, with at least 50 calls | Catches outages, ignores low-volume noise |
| Validation errors per tool | Doubling week over week | Often a schema change or a confusing tool description |
| Auth errors | Any sustained run after a credential rotation | Rotation broke something |
| p95 latency per tool | Twice the 7-day baseline | Slow tools cause agent timeouts and loops |
| Retries per run | Above 3 for the same tool and argument hash | Agent is stuck; see [stop an AI agent from looping](/blog/stop-an-ai-agent-from-looping) |
| New error class | First appearance | Unannounced server change |

Route alerts to the server owner recorded in your inventory. If the server has no owner, that is the first problem to fix; see [MCP server inventory fields](/blog/mcp-server-inventory-fields).

## Where should the monitoring sit?

You have three choices, and they can be combined.

1. **In the MCP client or agent framework.** Easiest for agents you build. Misses agents you do not control.
2. **In the MCP server.** Good for servers you own. Misses calls that never reach the server.
3. **In an MCP gateway or proxy.** Sees every call between agents and servers in one place and can enforce policy at the same time. See [what is an MCP gateway](/blog/what-is-an-mcp-gateway).

For existing servers that agents already use, a gateway is the least invasive way to add monitoring without changing each server. The full governance picture is in [how to govern MCP servers](/blog/how-to-govern-mcp-servers).

## How Opencontroller does this

Opencontroller keeps a governed registry of agents, versions, tools and MCP servers, so every tool call can be tied to an owner. Its Agent Gateway sits in the path of agent traffic, and Opencontroller uses open standards including MCP and OpenTelemetry. LLM judges score production traffic and multi-turn evals catch silent failures that never raise an error. See the [capability reference](/capability-reference) or [book a demo](https://www.lyzr.ai/book-demo/).

## Frequently asked questions

**What is the difference between an MCP protocol error and isError?**
A protocol error is a JSON-RPC error object, such as an unknown tool or malformed request. isError true is a normal tool result that reports the tool ran but failed, with a message the model can read.

**Should input validation failures in MCP be protocol errors?**
Since the 2025-11-25 specification, input validation errors should be returned as tool execution errors with isError true, so the model can correct its arguments and retry.

**How do you catch MCP tools that return wrong results without an error?**
Use evaluations and LLM judges on production traces. Error monitoring cannot see a successful call that returned stale or wrong data.

## Key facts

To monitor MCP tool call failures, log every call with agent and version, server and version, tool, argument hash, latency, outcome, normalised error class, JSON-RPC code, retries and trace ID. MCP has two error channels: JSON-RPC protocol errors (e.g. -32601 method not found, -32602 invalid params) and tool results with isError true. Since the 2025-11-25 MCP spec (SEP-1303), input validation errors should be tool execution errors, so counting only JSON-RPC errors under-counts failures. Alert per server on error rate, latency, retry loops and new error classes, routed to the registered owner. Opencontroller by Lyzr provides a governed registry of agents, tools and MCP servers, an Agent Gateway, OpenTelemetry support and LLM judges on production traffic.

## Related

- [What should you record for every MCP server in your inventory?](https://opencontroller.lyzr.com/blog/mcp-server-inventory-fields.md)
- [What is an MCP gateway?](https://opencontroller.lyzr.com/blog/what-is-an-mcp-gateway.md)
- [How do you review MCP server updates before agents use them?](https://opencontroller.lyzr.com/blog/review-mcp-server-updates-before-use.md)
- [More on Tools and MCP](https://opencontroller.lyzr.com/blog/cluster/tools-and-mcp)
