MCP (Model Context Protocol) — Velaro Integration Guide

What is MCP?

MCP (Model Context Protocol) is an open standard that lets AI systems call external tools during a conversation. In Velaro, any AI workflow node can call tools hosted on an MCP server — reading data, writing records, triggering actions — without the visitor ever leaving the chat.

Every MCP tool call happens within the conversation context: the AI has access to the visitor's name, the conversation history, variables captured earlier in the workflow, and the result of previous tool calls. This makes MCP far more powerful than a generic webhook.

Go to [→ MCP Servers](/integrations/mcp) to add and manage your MCP server connections.

---

Setting Up an MCP Server

Step 1 — Add the server

1. Go to [→ MCP Servers](/integrations/mcp)

2. Click Add Server

3. Enter the Server URL — this is the endpoint of your MCP server (e.g. https://tools.yourapp.com/mcp)

4. Set a display name (used when selecting the server in a workflow)

5. Add any required headers (e.g. Authorization: Bearer <token>)

6. Click Test Connection — Velaro fetches the tool manifest and lists available tools

7. Enable the server

Velaro discovers the tool list automatically from the server's tools/list endpoint (MCP standard). No manual tool registration needed.

Step 2 — Use tools in a workflow

1. Open [→ Workflows](/workflows)

2. Add an AI Chat node (or edit an existing bot)

3. In the AI node settings, select your MCP server under Available Tools

4. The AI will call tools automatically when they're relevant to the conversation

---

How the AI Calls MCP Tools

The AI decides when to call a tool based on the conversation. You do not need to wire explicit "call tool" steps.

Example flow:

Visitor: "Can you check if my order #5521 has shipped?"

AI sees: order_lookup tool available on MCP server
AI calls: order_lookup({ order_id: "5521", customer_email: "visitor@email.com" })
MCP server returns: { status: "shipped", tracking: "UPS 1Z..." }
AI replies: "Yes! Order #5521 shipped on March 8th. Tracking number: UPS 1Z..."

The AI automatically passes conversation variables (visitor email, name, etc.) to tool calls when the tool schema lists them as parameters.

---

Building Your Own MCP Server

An MCP server is any HTTPS endpoint that implements two routes:

| Route | Method | Purpose |

|-------|--------|---------|

| /tools/list | POST | Returns available tool definitions |

| /tools/call | POST | Executes a tool and returns the result |

Minimal tool definition (tools/list response)

{
  "tools": [
    {
      "name": "get_order_status",
      "description": "Look up the shipping status of a customer order by order ID",
      "inputSchema": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string", "description": "The order number" },
          "email": { "type": "string", "description": "Customer email for verification" }
        },
        "required": ["order_id"]
      }
    }
  ]
}

Tool execution (tools/call request/response)

Request from Velaro:

{
  "name": "get_order_status",
  "arguments": { "order_id": "5521", "email": "visitor@email.com" }
}

Your server responds:

{
  "content": [
    { "type": "text", "text": "Order 5521 shipped on 2026-03-08. Carrier: UPS. Tracking: 1ZX..." }
  ]
}

That's it. The AI incorporates your response into its reply naturally.

---

Orchestration: AI-to-AI Delegation via MCP

Velaro's AI Orchestration feature lets a specialist AI be called by a routing AI — each specialist can have its own MCP tools, knowledge base, and persona.

Enable this at [→ AI Bots](/bots) (requires EnableOrchestration on your plan).

Example: E-commerce + Appointment booking in one conversation

Customer: "I ordered a couch and want to schedule delivery."

Routing AI delegates to: order_specialist (has MCP tools: get_order, get_delivery_slots)
  order_specialist calls: get_order({ order_id: "7821" })
  → Returns order confirmed, ready to ship

order_specialist calls: get_delivery_slots({ zip: "90210", product_type: "furniture" })
  → Returns: Mon Mar 11, Wed Mar 13, Fri Mar 15

Routing AI delegates to: booking_specialist (has MCP tools: book_appointment, send_confirmation)
  booking_specialist books slot and sends calendar invite

Routing AI replies: "Your couch (order #7821) is ready to ship.
  I've booked delivery for Wednesday March 13th — you'll get a confirmation email shortly."

Each specialist bot is configured in [→ AI Bots](/bots) with its own MCP server and system prompt.

---

MCP Tool Examples by Use Case

CRM lookup

{
  "name": "lookup_customer",
  "description": "Find a customer record in your CRM by email or phone",
  "inputSchema": {
    "properties": {
      "email": { "type": "string" },
      "phone": { "type": "string" }
    }
  }
}

Inventory check

{
  "name": "check_inventory",
  "description": "Check if a product SKU is in stock and return quantity",
  "inputSchema": {
    "properties": {
      "sku": { "type": "string", "description": "Product SKU" },
      "location_id": { "type": "string", "description": "Warehouse location (optional)" }
    },
    "required": ["sku"]
  }
}

Create support ticket

{
  "name": "create_ticket",
  "description": "Create a support ticket in your helpdesk system",
  "inputSchema": {
    "properties": {
      "subject": { "type": "string" },
      "description": { "type": "string" },
      "priority": { "type": "string", "enum": ["low", "normal", "high", "urgent"] },
      "customer_email": { "type": "string" }
    },
    "required": ["subject", "customer_email"]
  }
}

---

Subscription Limits

| Limit | Default | Notes |

|-------|---------|-------|

| Max MCP servers | 3 | Contact support to increase |

| Max tool calls per conversation | 20 | Prevents runaway AI loops |

| Max tool calls per month | 1,000 | Resets monthly |

When the monthly limit is reached, the AI continues the conversation without MCP tools — it never crashes or errors out. To check your current usage, ask "What are my MCP usage stats?" in this chat.

---

Troubleshooting

AI isn't calling my tools — Check that the MCP server is Enabled in [→ MCP Servers](/integrations/mcp) and that the AI node has the server selected under Available Tools. The tool description must clearly describe when it should be called.

Tool returns an error — Use the Test button on the MCP server page to send a test call. Check that your server URL is accessible from the internet (not localhost). Headers like Authorization must be correct.

Too many tool calls — If the AI is calling tools in a loop, add a stopping condition to your workflow or reduce the MaxMcpCallsPerConversation limit via SuperAdmin.

Tool not appearing in list — Velaro fetches the tool manifest at connection time. After adding new tools to your server, go to [→ MCP Servers](/integrations/mcp) and click Refresh Tools on your server.