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

```http
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"
  }
}
```

| Field         | Required | Description                           |
| ------------- | -------- | ------------------------------------- |
| `name`        | No        | Display name for the MCP server       |
| `url`         | No        | Endpoint URL needed for a working MCP connection           |
| `description` | No        | Optional description                  |
| `headers`     | No        | Static headers to include in requests |

:::tip{title="Tip"}

Use [Variables](/docs/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

```http
GET /ai/mcp
```

**Response:**

```json
[
  {
    "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"
  }
]
```

### Link MCPs to your Assistant

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

```http
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:**

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

```http
GET /ai/toolDefinitions
```

The `configuration` field is a [JSON Schema](https://json-schema.org/) that defines the expected configuration for the tool. This configuration influences the Assistant's behavior when invoking the tool during a conversation.

**Response:**

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

```http
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:**

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

| Field                  | Required | Description                                                                                                                                                         |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `assistantId`          | Yes        | The Assistant to attach this tool to                                                                                                           |
| `definitionId`         | Yes        | The tool definition template to use                                                                                                                                 |
| `configuration`        | No        | Tool-specific properties based on the definition's `configuration`                                                                                                  |
| `descriptionOverride`  | No        | Replaces the default description shown to the LLM. Change it when you need different instructions for when to call the tool. |
| `disableInterruptions` | No        | Stored on the Tool, but currently not applied by the voice runtime. Use [VAD Settings](/docs/vad-settings#disableinterruptions) for Assistant-level interruption control                                                                                        |

<span id="delete--unbinding-a-tool" />

### Delete a tool

Delete the Tool instance to remove it from its Assistant.

```http
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:

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

**Response:**

```json
[
  {
    "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"
  }
]
```
