MCP Tools for Managed Agents

A managed agent can call external Model Context Protocol (MCP) servers during a conversation — looking up an order, checking the weather, searching your docs, or fetching anything else your server exposes as a tool. You configure the MCP servers once, on the Agent; every conversation through every route can then use them.

Think of MCP tools as abilities you lend to the avatar. The LLM decides when a conversation calls for a tool, Mirako runs the call against your server, and the avatar speaks the result — all in real time.

Note: This page is for managed agents. A custom agent owns its own tools: implement MCP (or anything else) inside your endpoint, and Mirako neither adds nor forwards tool configuration for it.

Mirako provides the native end_interaction tool alongside tools from your configured MCP servers. End of Conversation explains how the agent uses it to request a call ending.

Configure MCP Servers

MCP servers live in the Agent's tools field, as a JSON array. Each entry describes one MCP server:

With the CLI

--tools takes a JSON array string. Quote it carefully — a bare URL is not valid:

mirako agent create \
    --name "Store Assistant" \
    --avatar <MY_AVATAR_ID> \
    --voice <MY_VOICE_ID> \
    --instruction "You are a helpful store assistant. Use your tools to check stock before promising anything." \
    --tools '[{"name":"store","url":"https://mcp.example.com/mcp","authToken":"MY_MCP_TOKEN"}]'

For anything bigger than a one-liner, keep the JSON in a file and use --tools-file:

[
  { "name": "store", "url": "https://mcp.example.com/mcp", "authToken": "MY_MCP_TOKEN" },
  { "name": "weather", "url": "https://weather.example.com/mcp" }
]

mirako agent create \
    --name "Store Assistant" \
    --avatar <MY_AVATAR_ID> \
    --voice <MY_VOICE_ID> \
    --instruction-file ./assistant-instruction.md \
    --tools-file ./tools.json

With the API

import requests

API_KEY = "your_api_key_here"
BASE_URL = "https://mirako.co"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def create_agent_with_tools():
    """Create a managed agent that can call an MCP server."""
    response = requests.post(
        f"{BASE_URL}/v1/agents",
        headers=headers,
        json={
            "name": "Store Assistant",
            "avatar_id": "MY_AVATAR_ID",
            "voice_profile_id": "MY_VOICE_ID",
            "runtime_kind": "managed_agent",
            "instruction": (
                "You are a helpful store assistant. Use your tools "
                "to check stock before promising anything."
            ),
            "tools": [
                {
                    "name": "store",
                    "url": "https://mcp.example.com/mcp",
                    "authToken": "MY_MCP_TOKEN",
                }
            ],
        },
    )
    if response.status_code != 201:
        raise RuntimeError(
            f"Failed to create agent: {response.status_code} {response.text}"
        )
    return response.json()["data"]

How It Works

1. Configuration: You list MCP servers in the agent's tools field at creation (or later, via update).
2. Discovery: When a conversation starts, Mirako connects to each configured server and discovers the tools it offers.
3. Tool choice: The LLM sees the available tools and decides during the conversation when one would help.
4. Execution: Mirako calls your MCP server (with its authToken as a Bearer token, if set) and feeds the result back to the LLM.
5. Reply: The avatar answers the visitor using the tool result, in real time.

Your MCP server runs entirely on your infrastructure. You control what it exposes, what data it touches, and what it returns. Conversation content is only sent to your server when the LLM decides to call one of its tools.

MCP Server Requirements

To plug your own server into a managed agent:

• Follow the MCP specification — see modelcontextprotocol.io.
• Be reachable over HTTP(S) from the public internet (Cloudflare Workers, Vercel, your own host, and similar all work).
• Describe your tools well. The LLM picks tools from their names and descriptions — a tool called do_thing with no description will rarely be chosen; get_order_status(order_id) with "Look up the current status of a customer's order" will be.
• Keep responses focused. Tool results go back into the LLM's context. Return the facts the avatar needs to answer, not a full database dump.
• Fail clearly. If a tool call errors or times out, the avatar will explain the problem to the visitor and the conversation continues — but a clear error message makes for a much better explanation.

Multiple Servers, Multiple Tools

Because tools is an array, one agent can use several MCP servers at once, and one server can expose many tools. The LLM will choose across all of them based on the conversation. For example, a single server could offer:

• get_order_status — track a customer's order
• search_help_centre — find support articles
• get_store_hours — answer opening-hours questions by location

Update or Remove Tools

Tools are part of the agent configuration, so you change them the same way you change an instruction — through the Update Agent API. Send the complete new tools array; it replaces the old one:

def set_tools(agent_id, tools):
    """Replace the MCP server list of a managed agent."""
    response = requests.post(
        f"{BASE_URL}/v1/agents/{agent_id}/update",
        headers=headers,
        json={"tools": tools},
    )
    if response.status_code != 200:
        raise RuntimeError(
            f"Failed to update agent: {response.status_code} {response.text}"
        )
    return response.json()["data"]


# Remove all MCP servers
set_tools("MY_AGENT_ID", [])

The new configuration applies from the next conversation on every route — no links to re-share.

Going Next

• Share & Embed: Put your tool-equipped agent in front of visitors

Dive Deeper

• Create an Agent
• Agent Routes
• End of Conversation
• Building a Custom Agent — bring your own tools instead
• MCP Specification — the official protocol documentation