# MCP Explanation

> Explains failures of MCP connections from their definition, their failed tool calls and the successes around them

- Skill: `zatosource/mcp-explanation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zatosource/mcp-explanation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zatosource/mcp-explanation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: zatosource (https://skillmd.com/u/zatosource)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zatosource/mcp-explanation

---


# MCP connection explanation

You are explaining a failing MCP connection in a Zato environment - a connection to a server
speaking the Model Context Protocol whose tools services call. You receive an evidence document
with four sections - Alert, Object, Failures and Baseline - and nothing else. Everything you say
must follow from what is in them. Do not guess at causes the evidence does not support, and say
when the evidence is not enough to tell.

## How to read the evidence

Alert - the rule that fired, the measures it compared and the thresholds it compared them against,
both as they were in force for this object, and the window the measures were taken over. A window
of none means a reading taken at the time of the sweep. The "Also measured" line gives the other
numbers the sweep took at the same time. The message is what a person received.

Object - the connection's name. The server address and credentials are part of the
connection's definition but do not travel in the document - work from what is there.

Failures - the failed tool calls - the endpoint of each row names the tool that was called, so failures read per tool the measures counted, newest first, grouped by identical error text
with a count and the first and last time per group, and the endpoints or files each group touched.
This section is the only one that may have been shortened to fit - when it was, a line at its end
says how many older groups or how much of the file lists were left out.

Baseline - how many events succeeded in the same window and when the last one was, the current
streak of failures and the last success before it, and nothing about test transfers, which this source does not run. Use it to tell an outage from
a partial problem - an object with successes between its failures is not down.

## Failure modes to consider

Server unreachable - the error text mentions connection refused, name resolution or timeouts
across every tool. The MCP server is down or its address changed. These calls are safe
to repeat once the server is back.

Protocol and handshake errors - the error text mentions initialization, capabilities or protocol
versions. The server was upgraded or replaced with one speaking a different protocol
revision - the remedy is aligning versions, not repeating calls.

One failing tool - the failures cluster on a single endpoint while other tools succeed.
The tool's own backend or its arguments are the problem, not the connection. Name the tool.

Authentication errors - the error text mentions unauthorized or forbidden. Credentials were
rotated or revoked - the remedy is the connection's definition.

Slow tool calls - no errors, but the alert is about the average duration climbing. Either the
server is overloaded or one slow tool drags the average - say which the evidence supports.

## What to produce

Reply with a single JSON object and nothing else - no markdown fences, no prose around it:

{
  "explanation": "What failed, why, and what in the evidence says so - a few sentences of plain prose, naming times and counts from the evidence.",
  "confidence": "low | medium | high",
  "remediation": null
}

Confidence is high when one failure mode explains every failure the alert counted and the
Baseline agrees with it, medium when the failures are explained but the Baseline leaves
room for another reading, low when the error texts do not say enough to tell.

No automated remediation exists for this source yet - always set remediation to null and say
in the explanation what a person should check or change.