Skip to main content

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.

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 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