MCP servers

An MCP server (Model Context Protocol) is an endpoint that exposes one or more tools the AI can discover and use at runtime. It lets you evolve the tool set without touching the agent configuration: add a tool on your server and the AI sees it on the next discovery.

What an MCP server is

MCP is an open protocol based on JSON-RPC 2.0 over HTTP (Streamable HTTP). The server exposes primitives like tools/list and tools/call. yourang.ai queries your server at the start of every call to discover the tools, then exposes them to the AI as callable functions. Every invocation goes through your server, which runs the logic and replies.

How the AI communicates with the MCP server

1. 1

   Initial discovery

   When the call starts, yourang.ai sends a tools/list request to your MCP server. The server replies with the list of tools (name, description, parameter schema). Discovery carries no customer data: it only builds the tool catalogue.

2. 2

   MCP session

   The first response from the server returns an Mcp-Session-Id header. We reuse it on every subsequent request (tools/list and tools/call) within that voice call, so your server can keep state if needed.

3. 3

   Exposure to the agent

   Discovered tools are passed to the AI model as callable functions, alongside built-in tools and External Tools.

4. 4

   Invocation (tools/call)

   When the model decides to use an MCP tool, yourang.ai calls tools/call with the tool name + arguments. Along with the arguments we automatically attach a _meta.caller block with the customer metadata we know (see section below).

5. 5

   Reply to the AI

   The text content of the MCP response is extracted from content[].text blocks, concatenated and returned to the model as function output. The conversation continues.

JSON-RPC payload

The two requests your server will receive are simple and standard. Discovery does not pass metadata; invocation does.

{
 "jsonrpc": "2.0",
 "method": "tools/list",
 "params": {},
 "id": "<uuid>"
}

Customer metadata sent automatically

When the AI invokes a tool, yourang.ai enriches the request with a _meta.caller block carrying the current call context. They are standard fields, populated with what we already know about the customer at call time.

call_sid

Unique UUID of the current call. Useful to correlate your MCP-side logs with the call history in yourang.ai.

agent_id

UUID of the AI agent that invoked the tool. Use it if several agents share the same MCP server and you need to branch logic.

organization_id

Organization (tenant) UUID. Typically the first filter you apply on your server: every call belongs to a single tenant.

phone

Caller phone number in E.164 format (e.g. +1 415 555 0142), when available.

name

Contact name if we already have it in the address book for that number. Absent if the caller is unknown.

email

Contact email, if present in the contact record in yourang.ai.

contact_id

UUID of the contact in yourang.ai if the phone matched a record in the address book. Use it to fetch more data without going through a phone-based search.

How to configure one

1. 1

   Open the agent configuration

   /ai-agents → select the agent → MCP tab.

2. 2

   Enter URL and authentication

   HTTPS URL of the MCP server, authentication method (none, Bearer, API key, custom headers).

3. 3

   Save and check the discovery

   The panel shows the number of tools discovered last time and the timestamp. You can force a new discovery with one click.

4. 4

   Enable or disable individual tools

   Even if the server exposes 30 tools, you can enable only the 5 you need for that agent.

Authentication and headers

Every MCP request always includes the standard Content-Type and Accept, plus the auth header you configured and an Mcp-Session-Id we reuse across all requests of the same voice session.

# Sempre presenti
Content-Type: application/json
Accept: application/json, text/event-stream
Mcp-Session-Id: <restituito dal server alla prima risposta>

# Auth (in base alla configurazione)
Authorization: Bearer <token>
# oppure
X-API-Key: <chiave>

None

Public server. Only for testing or tools without sensitive data.

Bearer

Authorization: Bearer <token> header on every request.

API key

HTTP header of your choice (e.g. X-API-Key).

Custom headers

Multiple combinations (e.g. X-Tenant + X-Signature).

When to prefer MCP vs External Tool

• You have many related tools. An MCP server exposing 10 CRM tools (lookup, create, update, list, ...) is more manageable than 10 separate External Tools.
• You want to evolve the tool catalogue. Add tools on your server without touching the yourang.ai configuration: the next discovery picks them up.
• You need to talk to a single endpoint. An External Tool is lighter: less overhead, direct configuration.