Copy page

Integrations

MCP Tools

MCP (Model Context Protocol) is an open standard for connecting AI agents to external tools. With MCP, your Neuratel agents can look up customer records, book appointments, check inventory, and call any external API — all during a live phone conversation.

How MCP Works

1. You run an MCP server that exposes tools (functions the agent can call)
2. You connect the MCP server to your Neuratel organization
3. Neuratel discovers the server's tools automatically
4. During calls, the agent's LLM decides when to call a tool based on the conversation
5. Results are returned to the agent, which incorporates them into its response

The agent invokes tools transparently — from the caller's perspective, the agent simply knows things and can take actions.

Connect an MCP Server

Code
curl -X POST https://api.neuratel.ai/v1/integrations \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "mcp",
    "name": "CRM Tools",
    "url": "https://your-mcp-server.com/mcp",
    "auth_header": "Authorization",
    "auth_value": "Bearer your_mcp_server_token"
  }'

Code
import httpx

client = httpx.Client(
    base_url="https://api.neuratel.ai",
    headers={"Authorization": "Bearer nk_live_your_api_key"},
)

integration = client.post("/v1/integrations", json={
    "type": "mcp",
    "name": "CRM Tools",
    "url": "https://your-mcp-server.com/mcp",
    "auth_header": "Authorization",
    "auth_value": "Bearer your_mcp_server_token",
}).json()

integration_id = integration["id"]
print(integration_id)  # "int_abc123"

Code
const response = await fetch("https://api.neuratel.ai/v1/integrations", {
  method: "POST",
  headers: {
    Authorization: "Bearer nk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "mcp",
    name: "CRM Tools",
    url: "https://your-mcp-server.com/mcp",
    auth_header: "Authorization",
    auth_value: "Bearer your_mcp_server_token",
  }),
});
const integration = await response.json();

Response:

Code
{
  "id": "int_abc123",
  "type": "mcp",
  "name": "CRM Tools",
  "url": "https://your-mcp-server.com/mcp",
  "status": "connected",
  "created_at": "2025-04-07T10:00:00Z"
}

List Discovered Tools

Once connected, Neuratel queries the MCP server and discovers all available tools:

Code
curl https://api.neuratel.ai/v1/integrations/mcp/int_abc123/tools \
  -H "Authorization: Bearer nk_live_your_api_key"

Code
tools = client.get(f"/v1/integrations/mcp/{integration_id}/tools").json()
for tool in tools["items"]:
    print(f"{tool['name']}: {tool['description']}")

Code
const response = await fetch(
  `https://api.neuratel.ai/v1/integrations/mcp/${integrationId}/tools`,
  { headers: { Authorization: "Bearer nk_live_your_api_key" } }
);
const { items } = await response.json();

Response:

Code
{
  "items": [
    {
      "name": "lookup_customer",
      "description": "Look up a customer record by phone number or email address",
      "input_schema": {
        "type": "object",
        "properties": {
          "phone_number": { "type": "string", "description": "E.164 phone number" },
          "email": { "type": "string", "description": "Customer email address" }
        }
      }
    },
    {
      "name": "book_appointment",
      "description": "Book a service appointment for a customer",
      "input_schema": {
        "type": "object",
        "required": ["customer_id", "service_type", "date"],
        "properties": {
          "customer_id": { "type": "string" },
          "service_type": { "type": "string", "enum": ["consultation", "installation", "repair"] },
          "date": { "type": "string", "description": "ISO 8601 date" }
        }
      }
    }
  ]
}

The agent uses the tool names and descriptions to decide when to call each tool. Write clear, specific descriptions — they directly affect when the agent invokes a tool.

Assign MCP Integration to an Agent

An agent must be configured to use the MCP integration:

Code
curl -X PATCH https://api.neuratel.ai/v1/agents/agent_xyz789 \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "tools": {
      "mcp_integration_ids": ["int_abc123"]
    }
  }'

Code
client.patch(f"/v1/agents/agent_xyz789", json={
    "tools": {
        "mcp_integration_ids": ["int_abc123"],
    }
})

The agent now has access to all tools exposed by that MCP server. You can assign multiple MCP integrations to a single agent.

Building an MCP Server

An MCP server exposes a JSON-RPC endpoint that responds to tool discovery and tool call requests.

Minimal Python Example

Code
from fastapi import FastAPI
from pydantic import BaseModel
from typing import Any

app = FastAPI()

TOOLS = [
    {
        "name": "lookup_customer",
        "description": "Look up a customer record by phone number",
        "inputSchema": {
            "type": "object",
            "properties": {
                "phone_number": {"type": "string", "description": "E.164 phone number"}
            },
            "required": ["phone_number"],
        },
    }
]

@app.post("/mcp")
async def handle_mcp(request: dict[str, Any]):
    method = request.get("method")

    if method == "tools/list":
        return {"tools": TOOLS}

    if method == "tools/call":
        tool_name = request["params"]["name"]
        args = request["params"]["arguments"]

        if tool_name == "lookup_customer":
            # Replace with your actual CRM lookup
            customer = await your_crm.lookup(args["phone_number"])
            return {
                "content": [
                    {
                        "type": "text",
                        "text": f"Customer: {customer['name']}, Account: {customer['id']}, Status: {customer['status']}",
                    }
                ]
            }

    return {"error": {"code": -32601, "message": "Method not found"}}

Minimal Node.js Example

Code
const express = require("express");
const app = express();
app.use(express.json());

const TOOLS = [
  {
    name: "lookup_customer",
    description: "Look up a customer record by phone number",
    inputSchema: {
      type: "object",
      properties: {
        phone_number: { type: "string", description: "E.164 phone number" },
      },
      required: ["phone_number"],
    },
  },
];

app.post("/mcp", async (req, res) => {
  const { method, params } = req.body;

  if (method === "tools/list") {
    return res.json({ tools: TOOLS });
  }

  if (method === "tools/call") {
    const { name, arguments: args } = params;

    if (name === "lookup_customer") {
      const customer = await yourCRM.lookup(args.phone_number);
      return res.json({
        content: [
          {
            type: "text",
            text: `Customer: ${customer.name}, Account: ${customer.id}`,
          },
        ],
      });
    }
  }

  res.status(404).json({ error: { code: -32601, message: "Method not found" } });
});

app.listen(3000);

Example Use Cases

CRM Lookup

The agent looks up the caller's account before the conversation begins:

Code
System prompt: "When a call starts, use lookup_customer with the caller's phone number to retrieve their account details. Address them by name and reference their account status throughout the call."

Appointment Booking

The agent books appointments in your calendar system:

Code
System prompt: "When a caller wants to schedule a service appointment, ask for their preferred date, check availability using check_availability, then book using book_appointment. Confirm the booking details before ending the call."

Database Query

The agent checks live data during calls:

Code
System prompt: "Use check_order_status when a caller asks about their order. Always provide the current status and estimated delivery date."

Security

• MCP connections are scoped per organization — tools are only accessible to agents in your organization
• Neuratel sends requests to your MCP server using the auth_header and auth_value you configure
• Your MCP server should validate incoming requests using the auth credentials
• All traffic between Neuratel and your MCP server is over HTTPS

Managing Integrations

List All Integrations

Code
curl https://api.neuratel.ai/v1/integrations \
  -H "Authorization: Bearer nk_live_your_api_key"

Update an Integration

Code
curl -X PATCH https://api.neuratel.ai/v1/integrations/int_abc123 \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"auth_value": "Bearer new_token"}'

Delete an Integration

Code
curl -X DELETE https://api.neuratel.ai/v1/integrations/int_abc123 \
  -H "Authorization: Bearer nk_live_your_api_key"

Deleting an integration immediately removes it from all agents it was assigned to.

API Reference

Endpoint	Method	Description
/v1/integrations	GET	List all integrations
/v1/integrations	POST	Connect an MCP server
/v1/integrations/{id}	GET	Get integration details
/v1/integrations/{id}	PATCH	Update integration (URL, auth)
/v1/integrations/{id}	DELETE	Remove integration
/v1/integrations/mcp/{id}/tools	GET	List discovered tools

Next Steps

• Webhooks — receive call events and session reports
• Integrations Overview — all integration options
• Troubleshooting — resolve integration issues