> ## Documentation Index
> Fetch the complete documentation index at: https://docs.narrative.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server Error

> The MCP server returned a 5xx HTTP status or the workflow hit a network error reaching it.

**Surface:** `GET /agents/runs/{id}`, `error.type = "McpServerError"`

## When this error occurs

The HTTP call to the MCP server failed at the transport or 5xx-status layer:

* Connection refused / DNS resolution failed.
* TLS handshake error.
* 500 / 502 / 503 / 504 HTTP status.
* Connection reset mid-stream (for streaming `text/event-stream` responses).

Unlike `McpProtocol` (which means "we got a response but couldn't make sense of it"), this
class means "we never got a usable response at all".

This error **is retried** by the workflow with exponential backoff (1s → 2s → 4s → 8s →
giving up after 5 attempts). If you're seeing this on the run row, all retries exhausted.

## How to fix

* Verify the MCP server is reachable from the workers' VPC — try a manual JSON-RPC `tools/list`
  curl from inside the cluster.
* For self-hosted MCP servers, check the server's own logs around the failed timestamp.
* For third-party MCP servers (e.g. `docs.narrative.io/mcp`), check their status page or wait
  and retry — the failure is on their side.