Reecall

Tools and MCPs

Add System Tools for built-in actions or connect MCP servers to give your Assistant access to external tools.

Setting up MCP servers

The API paths below are relative to https://newprd.reecall.io/data_next.

MCP (Model Context Protocol) servers provide your Assistant with external tool capabilities. Each MCP server exposes a set of tools that the Assistant can invoke during conversations.

Register each MCP server with its URL and request headers, then attach it to an Assistant.

Registering a new MCP server

Create an MCP server configuration:

Code
POST /ai/mcp Content-Type: application/json Authorization: Bearer <your-api-token> { "name": "Weather Service", "description": "Provides weather information", "url": "https://mcp.example.com/weather", "headers": { "X-Custom-Header": "value" } }
FieldRequiredDescription
nameNoDisplay name for the MCP server
urlNoEndpoint URL needed for a working MCP connection
descriptionNoOptional description
headersNoStatic headers to include in requests

Tip

Use Variables in header values and URLs, for example Authorization: "{ mcp_apikey }".

Although the API does not require url, set a valid HTTP MCP endpoint for the Assistant to connect successfully.

Fetch available MCP servers

Code
GET /ai/mcp

Response:

JSONCode
[ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Calendar Integration", "description": "Provides calendar management capabilities", "url": "https://mcp.example.com/calendar", "headers": {}, "createdAt": "2024-01-01T00:00:00.000Z", "updatedAt": "2024-01-01T00:00:00.000Z" } ]

Update your Assistant with the mcpIds array containing the IDs of MCP servers you want to attach:

Code
PATCH /conversational/assistants/{assistantId} Content-Type: application/json Authorization: Bearer <your-api-token> { "mcpIds": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] }

Response:

JSONCode
{ "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "name": "Customer Support Assistant", "mcpIds": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "b2c3d4e5-f6a7-8901-bcde-f12345678901" ], "...": "other fields" }

Setting up system tools

Configure each System Tool separately and attach it directly to an Assistant. Reecall provides the tool definitions that specify the available actions and their configuration.

Understanding the tool architecture

Tools consist of two parts:

  1. A ToolDefinition is a Reecall-provided template that defines the tool's schema and configuration.
  2. A Tool is an instance you create from that definition, with configuration for a specific Assistant.

Fetch available tool definitions

Code
GET /ai/toolDefinitions

The configuration field is a JSON Schema that defines the expected configuration for the tool. This configuration influences the Assistant's behavior when invoking the tool during a conversation.

Response:

JSONCode
[ { "id": "d4e5f6a7-b8c9-0123-def0-123456789abc", "name": "end_conversation", "description": "End the conversation gracefully when appropriate. Call this function when the user explicitly says goodbye or wants to end the call.", "configuration": { "type": "object", "properties": { "closingMessage": { "type": "string", "description": "Optional custom closing message to say before ending the conversation" } }, "additionalProperties": false }, "createdAt": "2024-01-01T00:00:00.000Z", "updatedAt": "2024-01-01T00:00:00.000Z" }, { "id": "another-definition-id", "name": "another_tool", "description": "Another available tool" } ]

The end_conversation tool speaks closingMessage, when provided, before ending the call.

Create a tool for your Assistant

Create a Tool with the assistantId to attach it to and the definitionId returned by GET /ai/toolDefinitions. Set configuration according to that definition's schema.

Code
POST /ai/tools Content-Type: application/json Authorization: Bearer <your-api-token> { "assistantId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "definitionId": "d4e5f6a7-b8c9-0123-def0-123456789abc", "configuration": { "closingMessage": "Thank you for calling! Have a great day!" }, "descriptionOverride": "End the call politely when the customer is done", "disableInterruptions": true }

Response:

JSONCode
{ "id": "e5f6a7b8-c9d0-1234-ef01-23456789abcd", "assistantId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "definitionId": "d4e5f6a7-b8c9-0123-def0-123456789abc", "definition": { "id": "d4e5f6a7-b8c9-0123-def0-123456789abc", "name": "end_conversation", "description": "End the conversation gracefully when appropriate." }, "configuration": { "closingMessage": "Thank you for calling! Have a great day!" }, "descriptionOverride": "End the call politely when the customer is done", "disableInterruptions": true, "createdAt": "2024-01-15T10:30:00.000Z", "updatedAt": "2024-01-15T10:30:00.000Z" }

Tool configuration options

FieldRequiredDescription
assistantIdYesThe Assistant to attach this tool to
definitionIdYesThe tool definition template to use
configurationNoTool-specific properties based on the definition's configuration
descriptionOverrideNoReplaces the default description shown to the LLM. Change it when you need different instructions for when to call the tool.
disableInterruptionsNoStored on the Tool, but currently not applied by the voice runtime. Use VAD Settings for Assistant-level interruption control

Delete a tool

Delete the Tool instance to remove it from its Assistant.

Code
DELETE /ai/tools/{toolId} Authorization: Bearer <your-api-token>

List tools for an Assistant

Filter Tools by assistantId to list those attached to an Assistant:

Code
GET /ai/tools?where={"assistantId":"f47ac10b-58cc-4372-a567-0e02b2c3d479"}

Response:

JSONCode
[ { "id": "e5f6a7b8-c9d0-1234-ef01-23456789abcd", "assistantId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "definitionId": "d4e5f6a7-b8c9-0123-def0-123456789abc", "definition": { "id": "d4e5f6a7-b8c9-0123-def0-123456789abc", "name": "end_conversation", "description": "End the conversation gracefully when appropriate." }, "configuration": { "closingMessage": "Thank you for calling! Have a great day!" }, "descriptionOverride": "End the call politely when the customer is done", "disableInterruptions": true, "createdAt": "2024-01-15T10:30:00.000Z", "updatedAt": "2024-01-15T10:30:00.000Z" } ]
Last modified on