---
title: MCP servers
description: Protocol-level monitoring for MCP servers — initialize handshake, tool inventory, drift detection with a diff, version pinning. Read-only, never tools/call.
canonical: https://watchfor.io/docs/monitors/mcp
---

# MCP servers

Protocol-level monitoring for MCP servers — initialize handshake, tool inventory, drift detection with a diff, version pinning. Read-only, never tools/call.

An **MCP monitor** checks a [Model Context Protocol](https://modelcontextprotocol.io)
server the way a real AI agent does: it performs the full JSON-RPC
`initialize` handshake over Streamable HTTP, negotiates the protocol version,
discovers capabilities and walks the complete tool inventory.

That matters because an MCP server can answer HTTP `200` and still be broken
for every AI agent connected to it — a failed handshake behind a misconfigured
proxy, an empty tool list after a bad deploy, or auth silently rejecting every
session. A plain uptime check can't see any of that.

**Target:** the server's endpoint URL, e.g. `https://mcp.example.com/mcp`.

## What each check does

1. **Initialize handshake** — a real JSON-RPC `initialize` exchange (JSON and
   SSE response modes both supported), offering the latest protocol version
   and recording what the server negotiates. Session handling
   (`Mcp-Session-Id`) and the `MCP-Protocol-Version` header follow the spec,
   including the `notifications/initialized` notification.
2. **Tool inventory** — `tools/list` is walked with pagination;
   `resources/list` and `prompts/list` are counted when the server advertises
   those capabilities.
3. **Phase timings** — DNS, TCP, TLS, `initialize` and `tools/list` are timed
   separately, so a serverless cold start looks different from a slow network
   path.
4. **Clean teardown** — the session is explicitly terminated, as the spec asks
   of well-behaved clients.

Checks are **read-only discovery** — `tools/call` is never issued, so
monitoring can't trigger tool side effects.

## Tool drift detection

On every check the entire inventory — tool **names, descriptions and input
schemas** — is hashed into a fingerprint. When it changes, the monitor records
exactly which tools were **added**, **removed** or **changed**, and the
**Tool Inventory Changed** rule (on by default) fires with that diff.

Why descriptions matter: they are delivered verbatim into an AI agent's
context — they are instructions. A description that quietly changes after
you've connected is the MCP **rug-pull** pattern, and it is precisely what
drift detection catches. The full change history lives on the monitor's
Overview under **Inventory changes**.

## Setup

1. Create a monitor with type **MCP Server** and set the target to your
   endpoint URL.
2. For protected servers, add a **Bearer token** under
   **Settings → Advanced Options**; it is sent as `Authorization: Bearer …`.
3. To watch the protocol version, enable **Protocol Version Mismatch** on the
   **Alerting** tab and enter the version to pin right on the rule — it fires
   when a deploy negotiates anything else.

Supported transport: **Streamable HTTP** (the standard for remote MCP
servers). `stdio` servers are local-process-only by design — monitor their
host service or use a [heartbeat](/docs/monitors/heartbeat) instead.

## Alert rules

| Preset | Default | Fires when |
| --- | --- | --- |
| **Status (Up / Down)** | on | Handshake or tool listing fails — 3 consecutive failures open the incident. |
| **Tool Inventory Changed** | on | Any tool added, removed or modified since the previous check. |
| **No Tools Exposed** | on | The server initializes but exposes zero tools. |
| **Slow Handshake** | off | `initialize` exceeds your latency threshold. |
| **SSL Certificate** | off | The endpoint's certificate is within *N* days of expiry. |
| **Protocol Version Mismatch** | off | The negotiated version differs from the one you pinned. |

Drift is a one-shot observation (the probe re-baselines after reporting), so
MCP monitors skip the accelerated multi-location confirmation phase other
types use; the availability rule's own threshold applies. See
[Locations & scheduling](/docs/monitors/scheduling#types-with-a-different-confirmation-policy).

The alert metrics for the API are `success`, `metrics['mcp.inventory_changed']`,
`metrics['mcp.tools_count']`, `metrics['mcp.handshake_time_ms']` and
`metrics['mcp.version_match']` — see
[MCP Server in the type catalog](/docs/api/monitor-types#mcp-server).

## Quick one-off check

Not monitoring yet? The free [MCP Server Checker](/mcp-server-checker) runs the
same protocol-level check once, from a location near you — no account needed.

## Also via API

Create with `type: "mcp"` and an optional `config.bearerToken` — see
[Monitors API](/docs/api/monitors#create-a-monitor). WatchFor itself is also
an MCP server: AI agents can create and inspect monitors through it — see
[MCP server](/docs/api/mcp).

---

Canonical page: https://watchfor.io/docs/monitors/mcp · All docs: https://watchfor.io/docs · Site guide: https://watchfor.io/llms.txt