Adding MCP Tools to Your Avatar

MCP tools let your avatar act, not just talk: book appointments, look up orders, capture leads in your CRM, check availability, and more. Your avatar connects to one or more MCP servers — services that expose actions through the open Model Context Protocol (MCP) standard — and the AI agent calls those actions in real time during a conversation.

The good news: you don't need to develop anything to get started. There are three ways to get an MCP server, from no-code to fully custom.

---

Option 1 — Use an MCP Platform like Zapier (no code)

MCP platforms let you turn everyday business actions into avatar tools in minutes. For example, with Zapier MCP you can expose actions from thousands of connected apps — book a meeting in Google Calendar or Calendly, add a lead to HubSpot, append a row to a spreadsheet, send a Slack message — without writing any code:

1. Create an MCP server on the platform and pick the specific actions you want your avatar to perform.

2. Copy the server's endpoint URL and its authentication header.

3. In your avatar's training (Tools tab), add an MCP tool entry with that URL and header. See Training Avatars.

4. Save, then test by asking the avatar to perform the task (e.g., “Can you book me an appointment for Thursday?”).

Other MCP platforms and automation services offer similar hosted MCP servers — the same steps apply: get a URL and credentials from the platform, paste them into Sentifyd.

Tip: Expose only the few actions your avatar actually needs. A short, focused list of clearly named actions makes the agent far more reliable than dozens of loosely related ones.

Option 2 — Use a Ready-Made MCP Server from Your Vendor

More and more SaaS products — booking systems, e-commerce platforms, help desks — ship their own MCP endpoints. If a system you already use offers one, ask your vendor for the MCP endpoint URL and an API token, and connect it the same way.

Option 3 — Build Your Own MCP Server (advanced)

For full control — custom business logic, direct database lookups, internal APIs — you (or your developer) can build a custom MCP server. The rest of this page covers what you need to know.

---

How the Connection Works

1. You add an MCP tool entry to your avatar's training (Tools tab): a name, a connection type, the server's endpoint URL, and optional headers.

2. When a conversation starts, Sentifyd connects to the MCP server, discovers the tools it exposes, and makes them available to the AI agent alongside the built-in tools.

3. When the user asks for something a tool can do, the agent calls it, waits for the response, and weaves the result into its spoken or written reply.

The connection is made from Sentifyd's servers — the user's browser never talks to your MCP server, and your endpoint URL and headers are never exposed to end users.

Server Requirements

• Transport: Streamable HTTP (recommended) or SSE (legacy). Hosted platforms like Zapier use Streamable HTTP.

• Reachability: The endpoint URL must be publicly reachable. For security, URLs that point to private or local addresses (e.g., localhost, LAN IPs) are rejected. Use HTTPS in production.

• Startup speed: The server must respond to the initial connection and tool listing within a few seconds. If it doesn't, its tools are skipped for that conversation — the avatar still works, just without those tools.

• Tool call speed: Aim for tool responses well under 5 seconds — the user is waiting in a live voice conversation. Calls that take longer than about 30 seconds are abandoned.

Authentication

Use the Headers (JSON) field to pass credentials with every request Sentifyd makes to the server:

{ "Authorization": "Bearer YOUR-SECRET-TOKEN" }

A custom MCP server should validate the token and reject unauthenticated requests — the endpoint is on the public internet. Your credentials are kept confidential by Sentifyd.

Tool Naming

• Tool names exposed by the server are automatically prefixed with the tool entry's name you configured in Sentifyd, so tools from multiple servers can't clash.

• Keep tool names short, lowercase, and descriptive, using only letters, digits, _, ., or - — e.g., get_order_status, book_table.

Designing Tools for Voice Conversations

The agent decides when to call your tools based on their names and descriptions, so treat those as part of your prompt engineering:

• Write clear descriptions. Describe exactly what each tool does, when to use it, and what each parameter means. This is the single biggest factor in whether the agent uses your tool correctly.

• Expose few, focused tools. A handful of well-described tools outperforms dozens of overlapping ones.

• Return concise results. The response is fed to a language model and often spoken aloud. Return short, structured text or compact JSON — not full HTML pages or large payloads.

• Be fast. Every second of tool latency is a second of silence for the user.

• Fail gracefully. Return a clear, human-readable error message (e.g., "Order 1234 was not found") rather than a technical error. Error messages are passed back to the agent, so a good one lets the avatar explain the problem and try again.

Minimal Custom Server Example (Python + FastMCP)

# pip install fastmcp
from fastmcp import FastMCP

mcp = FastMCP("orders")

@mcp.tool
def get_order_status(order_id: str) -> str:
    """Look up the shipping status of a customer order by its order number."""
    # Replace with a real lookup against your database or API
    return f"Order {order_id} shipped on July 3 and arrives Thursday."

if __name__ == "__main__":
    # Serves the MCP endpoint over Streamable HTTP
    mcp.run(transport="http", host="0.0.0.0", port=8000)

Deploy it behind HTTPS (e.g., https://tools.example.com/mcp), then configure the tool in Sentifyd:

• Name: orders

• Connection Type: Streamable HTTP

• Endpoint URL: https://tools.example.com/mcp

• Headers (JSON): { "Authorization": "Bearer YOUR-SECRET-TOKEN" }

Testing & Troubleshooting

• For custom servers, test first with the MCP Inspector (npx @modelcontextprotocol/inspector) to confirm the tool list and calls work before wiring it to Sentifyd.

• After saving the training, start a conversation and ask a question that should trigger the tool.

• Tools not being used? Check that the endpoint is publicly reachable (not a private/localhost address), responds quickly to the initial connection, and that the tool descriptions clearly match the kinds of questions you're asking.

• If one MCP server is down, other configured MCP servers and built-in tools continue to work — failures don't spread.