MCP tools

Tried agents can call tools on any Model Context Protocol server reachable over Streamable HTTP. You register the server once under MCP Servers, then add an MCP Tool function for each remote tool the agent may use. Conversation flows can also call an MCP tool at a fixed step with an MCP node.

Step 1: add an MCP server#

Servers live on the agent's response engine: mcps[] on the Retell LLM (single and multi-prompt agents) or on the conversation flow.

1. Open the agent and expand MCP Servers in the settings column (in a flow, under Global settings).
2. Click Add MCP server.
3. Set the name and the URL (for example https://mcp.example.com/mcp). Invalid URLs are outlined in red and are not saved.
4. Set Timeout in seconds (1 to 600, default 30).
5. Optional: open Headers and query parameters to add authentication headers such as Authorization: Bearer {{mcp_token}}, or query parameters.

{
  "mcps": [
    {
      "id": "mcp_8c2f1a90",
      "name": "Orders",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer {{mcp_token}}" },
      "timeout_ms": 20000
    }
  ]
}

Step 2: add an MCP Tool function#

1. Expand Functions, click Add and choose MCP Tool.
2. Name and Description: when the agent should call it.
3. MCP server: pick one of the agent's servers. If the list is empty, the field says "Add a server under MCP Servers first."
4. Tool name on the server: pick from the tools the server lists, or choose Type a name. It defaults to the function's name.
5. Parameters: the arguments the LLM fills in. Copy the remote tool's input schema here.
6. Response variables: values to save from the result.
7. Save. The modal needs a server (or an inline URL through the API).

The tool list comes from GET /get-mcp-tools/:agent_id?mcp_id=..., which connects to the saved server and lists its tools. Save the server on the agent first; if listing fails, the field shows "Couldn't list this server's tools" and you can type the name.

Fields#

{
  "type": "mcp",
  "name": "lookup_order",
  "description": "Look up an order once the caller gives the order number.",
  "mcp_id": "mcp_8c2f1a90",
  "mcp_tool_name": "get_order",
  "parameters": {
    "type": "object",
    "properties": { "order_id": { "type": "string", "description": "Order number, e.g. A1234" } },
    "required": ["order_id"]
  },
  "response_variables": { "order_status": "$.status" }
}

Protocol details#

The worker implements the client side of MCP protocol version 2025-06-18 over Streamable HTTP:

1. POST initialize, keeping any Mcp-Session-Id header the server returns.
2. POST notifications/initialized.
3. POST tools/call with mcp_tool_name and the LLM's arguments.

Every request sends Accept: application/json, text/event-stream. Responses can be plain JSON or a server-sent event stream. The session is reused for later calls to the same server URL during the same call.

Results#

• The text content of the tool result goes to the LLM, cut to 15,000 characters.
• If the server marks the result as an error, the LLM gets Error: <text>.
• response_variables read from the result's structuredContent. When there is none, the worker tries to parse the text content as JSON.
• Connection failures return Error: MCP call failed: .... An unknown mcp_id returns Error: MCP server <id> is not configured.

MCP requests go through the same guarded HTTP client as custom functions, so private and metadata addresses are refused. See custom function security.

Gotchas#

• One MCP Tool function maps to one remote tool. Add a function per remote tool the agent should use, with a description written for your use case.
• The LLM sees your parameters, not the server's schema. Keep them in sync when the server changes.
• The client sends only the headers and query parameters you configure. It has no OAuth sign-in flow, so authenticate with a token in a header.

Related#