> For the complete documentation index, see [llms.txt](https://docs.sentifyd.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sentifyd.io/features/adding-mcp-tools-to-your-avatar.md).

# 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)](https://modelcontextprotocol.io/) 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](https://zapier.com/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](/features/markdown.md).
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.

{% hint style="success" %}
**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.
{% endhint %}

### 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.

{% hint style="info" %}
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.
{% endhint %}

### 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:

```json
{ "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)

```python
# 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](https://modelcontextprotocol.io/docs/tools/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.