MCP Integration

What is MCP?

The Model Context Protocol is an open standard for connecting AI models to external tools and data sources. Instead of building custom integrations, you define tools once and any MCP-compatible system can use them.

With Aployee + MCP:

Your MCP server defines available tools
Aployee decides when to call tools based on conversation
Tool results are woven naturally into the dialogue
State stays in Aployee; business logic stays in your tools

MCP vs Webhooks

Aspect	Webhook	MCP
Control	You decide what to do with each utterance	Aployee decides when to call tools
Best for	Complex business logic, custom LLMs	Simple tool calls, integrations
State	You manage state	Aployee manages state
Setup	Single endpoint	MCP server with tool definitions

Configuration

Enable MCP by setting reasoning_mode: "mcp" and providing your server URL:

Assistant Config

// Configure MCP server in assistant settings
{
  "name": "CustomerServiceBot",
  "reasoning_mode": "mcp",
  "mcp_config": {
    "server_url": "https://your-mcp-server.com",
    "tools": [
      "lookup_customer",
      "check_order_status",
      "schedule_callback",
      "create_ticket"
    ]
  }
}

Building an MCP Server

Use the official MCP SDK to create a server that exposes your tools:

mcp-server.ts

import { Server } from "@modelcontextprotocol/sdk/server";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio";

const server = new Server({
  name: "customer-service-tools",
  version: "1.0.0"
});

// Define available tools
server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "lookup_customer",
      description: "Look up customer information by phone number or account ID",
      inputSchema: {
        type: "object",
        properties: {
          phone: { type: "string", description: "Customer phone number" },
          account_id: { type: "string", description: "Customer account ID" }
        }
      }
    },
    {
      name: "check_order_status",
      description: "Check the status of an order",
      inputSchema: {
        type: "object",
        properties: {
          order_id: { type: "string", description: "Order ID to look up" }
        },
        required: ["order_id"]
      }
    }
  ]
}));

// Handle tool calls
server.setRequestHandler("tools/call", async (request) => {
  const { name, arguments: args } = request.params;

  switch (name) {
    case "lookup_customer":
      const customer = await db.customers.findOne({
        $or: [{ phone: args.phone }, { accountId: args.account_id }]
      });
      return { content: [{ type: "text", text: JSON.stringify(customer) }] };

    case "check_order_status":
      const order = await db.orders.findOne({ orderId: args.order_id });
      return { content: [{ type: "text", text: JSON.stringify(order) }] };

    default:
      throw new Error(`Unknown tool: ${name}`);
  }
});

// Start server
const transport = new StdioServerTransport();
await server.connect(transport);

Tool Call Flow

Here's how a tool call flows through the system:

Flow Example

// 1. User says: "Where's my order 12345?"

// 2. Aployee recognizes tool need, calls your MCP server:
{
  "method": "tools/call",
  "params": {
    "name": "check_order_status",
    "arguments": { "order_id": "12345" }
  }
}

// 3. Your server returns:
{
  "content": [{
    "type": "text",
    "text": "{ \"status\": \"shipped\", \"carrier\": \"UPS\", \"tracking\": \"1Z999...\" }"
  }]
}

// 4. Aployee speaks: "Your order 12345 has shipped via UPS.
//    Would you like the tracking number?"

Tool Design Guidelines

Clear Names

Use descriptive names like check_order_status notcos. The model uses names to decide when to call tools.

Good Descriptions

Tool descriptions help the model understand when to use each tool. Be specific about what the tool does and what inputs it needs.

Simple Inputs

Keep input schemas simple. Prefer strings and numbers over complex nested objects. The model extracts these from conversation.

Useful Output

Return data that helps the assistant respond. Include relevant details the user might ask about next.

Security

Authentication: Aployee authenticates to your MCP server using the credentials you provide
HTTPS Required: All MCP communication uses TLS
Tool Allowlist: Only tools you explicitly list are available to the assistant
No Arbitrary Code: Tools execute your code on your infrastructure