> ## 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 Discovery Failed

> A registered MCP server failed to respond to tools/list — either at the start of a run, or during synchronous tool_choice validation.

**HTTP / status:** Surfaces on two paths.

* **Synchronous (`POST /agents/conversations/{id}/runs`)**: HTTP 400 RFC 7807 with
  `type` URL pointing to this page. Triggered by `tool_choice: { kind: "specific_tool",
  mcp_alias: "...", name: "..." }` — the platform does a targeted `tools/list` against
  the named server to confirm the tool exists before accepting the run. The 400 (not 5xx)
  reflects that the failure is caller-actionable: the MCP server you registered isn't
  responding, and fixing it is on you.
* **Asynchronous (run-time)**: the run lands in `status: failed` with
  `error.type = "AgentLoopMcpDiscoveryFailed"`. Triggered at workflow start when the
  load activity fans out one `tools/list` per registered MCP server to build the
  inference catalog.

## When this error occurs

The Agent Conversations API doesn't keep a cached MCP catalog. Every run rediscovers each
registered server's `tools/list`, and `tool_choice` with an `mcp_alias` re-discovers that
single server synchronously. Common failure modes:

* The MCP server URL is unreachable (DNS, firewall, TLS handshake failure).
* The MCP server returns 5xx (transient outage or unhandled exception server-side).
* The MCP server responds, but the body isn't a well-formed JSON-RPC envelope.
* The MCP server doesn't implement `tools/list` (responds with `-32601 method not found`).

## How to fix

* Verify the MCP server URL is reachable from the platform's outbound workers. For
  public servers, try `curl -X POST $URL` with a minimal initialize JSON-RPC body. For
  private/VPC-only servers, confirm the network path from the data plane.
* Check the server's logs for crashes or rate-limit errors around the failure timestamp.
* Confirm the server exposes both `initialize` and `tools/list` per the
  [Model Context Protocol](https://modelcontextprotocol.io/) wire spec.
* If the MCP server is permanently down, drop the entry from `mcp_servers` (or override
  the conversation defaults via `config_override.mcp_servers` on the affected run) — the
  agent loop can't proceed without a working catalog for every registered server.

## See also

* [`tool_choice` reference](/reference/architecture/agent-conversations#tool-choice) —
  the API field that drives the synchronous discovery hop.
* [Unknown Tool Choice Name](/reference/architecture/agent-conversations/errors/unknown-tool-choice-name)
  — discovery succeeded but the named tool wasn't in the returned catalog.