Monitor MCP Servers

An MCP server can return HTTP 200 while being unusable to every agent that depends on it. The process is listening, but the initialize handshake fails, a tool your agents rely on has vanished from the catalog, or a tool's input schema changed shape underneath a caller that worked yesterday. None of those move an HTTP status code.

MCP monitors exercise the server the way a real client does. Every run executes the full JSON-RPC session over Streamable HTTP:

1. Sends initialize and asserts the response carries protocolVersion and capabilities, capturing any Mcp-Session-Id for the rest of the session.
2. Sends the notifications/initialized notification.
3. Calls tools/list and verifies every tool in expectedTools is present (if configured).
4. Runs each testCalls entry: invokes the tool and checks the result contains expectedOutputContains (if provided).
5. Hashes each tool's input schema and reports tools added, removed, or modified since the previous run (when detectSchemaDrift is enabled).

A failure names the phase that broke (handshake, missing tool, drift, wrong output), not a generic timeout.

Before you start

• Your server must speak the Streamable HTTP transport. This is the standard remote transport; a typical endpoint looks like https://example.com/mcp. Servers that only run over stdio are local processes and cannot be monitored externally.
• If the server requires auth, have the credential ready. Yorker supports basic, bearer, and api-key auth, with secrets pulled from your team's secret store so tokens never live in config files.

Create the monitor (Web UI)

1. Open the dashboard, click Create Monitor, and select the MCP tab.
2. Enter the Streamable HTTP endpoint URL.
3. Optionally list the tool names your agents require. A missing tool fails the check.
4. Optionally add test calls: a tool name, arguments, and a substring the result must contain.
5. Choose locations and frequency, then click Create. The first run starts immediately.

Create the monitor (YAML)

monitors:
  - name: Docs MCP Server
    type: mcp
    endpoint: https://mcp.example.com/mcp
    frequency: 5m
    locations:
      - loc_us_east
    auth:
      type: bearer
      token: "{{secrets.MCP_TOKEN}}"
    expectedTools:
      - search_docs
      - fetch_page
    testCalls:
      - toolName: search_docs
        arguments:
          query: "pricing"
        expectedOutputContains: "Plans"
    detectSchemaDrift: true

Deploy with yorker deploy. The full field reference is in Configuration. Note that MCP monitors cannot be executed locally with yorker test; deploy them and watch results with yorker results tail or the dashboard.

What schema drift catches

When detectSchemaDrift is enabled (the default), each tool's inputSchema is hashed with a deterministic, key-sorted JSON representation, so equivalent schemas always hash identically regardless of key order. Each run diffs the current hashes against the previous run's and reports every tool as added, removed, or modified. The first run has no baseline, so it seeds one and reports no drift.

This is the failure mode that breaks agents quietly: the server is up, the tool exists, but its arguments changed shape and every caller built against the old schema now fails. Drift surfaces that as a reportable change the moment it ships, instead of leaving your agents to discover it.

Alerting and telemetry

MCP monitors plug into the same alert rules as HTTP and browser monitors: consecutive failures, multi-location correlation, and notification channels are configured identically. See Set Up Alerts.

Results emit as standard OTLP to your configured backend, with per-phase timing for the initialize, tools/list, and test-call phases, the discovered tool catalog, and the computed drift. When a run detects drift and your team has an OTLP endpoint configured, Yorker forwards a synthetics.mcp.schema_drift event carrying per-change-type counts (synthetics.mcp.drift.added_count, removed_count, modified_count, total_count) and the affected tool names (capped at 50 per list). The event fires only when drift is present.

Billing

A full MCP session (handshake, tool catalog, schema hashing, and any tool calls you configure) bills as one run at the HTTP rate: 10,000 HTTP + MCP runs a month on the free tier, unlimited on the paid plan.

Troubleshooting

• "Streamable HTTP transport may not be supported": the endpoint answered with HTML or a non-JSON content type. Check that the URL is the MCP endpoint itself (commonly /mcp), not a documentation page or an SSE-only path.
• Handshake fails with a valid endpoint: the response must be a JSON-RPC success carrying protocolVersion and capabilities. Yorker sends Accept: application/json on every request; a server that insists on text/event-stream in the Accept header before answering will fail at this phase. A server that rejects the initialize payload fails with the JSON-RPC error surfaced in the result.
• HTTP 401/403: the server requires auth. Add an auth block; for a bearer-token server, use type: bearer with the token stored as a team secret.
• Expected tool missing intermittently: some servers assemble their catalog from downstream services. Pair expectedTools with a multi-location alert rule so a single flaky assembly does not page you.