---
summary: "The ScaiDial tools AI agents get through ScaiGrid's MCP server \u2014 directory\
  \ lookup, personal settings, and live call control including transfers, conferences\
  \ and speaking into a call."
title: MCP tools
path: reference/mcp-tools
status: published
---

ScaiDial registers its tools with ScaiGrid's MCP server, so an agent (a ScaiCore agent, a bot with tools, any MCP client) can look people up and work with live calls. Tools act as the calling identity: its tenant, and the permission each tool lists. Arguments marked `?` are optional.

## Directory and calls

| Tool | Arguments | Permission | Does |
|---|---|---|---|
| `scaidial.directory.lookup` | `query`, `limit?` | `scaidial:calls:observe` | Find extensions by number or name |
| `scaidial.call.list_active` | `limit?` | `scaidial:calls:observe` | Calls in progress with their legs |
| `scaidial.extension.get` | `extension_id` | `scaidial:calls:observe` | One extension's settings |

## Personal settings

| Tool | Arguments | Permission |
|---|---|---|
| `scaidial.user.set_dnd` | `extension_id`, `enabled`, `until?` | `scaidial:extensions:own` |
| `scaidial.user.set_forward` | `extension_id`, `condition`, `forward_to`, `condition_params?`, `priority?` | `scaidial:extensions:own` |
| `scaidial.user.set_ring_timeout` | `extension_id`, `seconds?` | `scaidial:extensions:own` |
| `scaidial.user.set_assistant_pickup` | `extension_id`, `seconds?` | `scaidial:extensions:own` |

## Call control

All need `scaidial:calls:observe`. `leg_id` values come from `scaidial.call.list_active`. Behaviour as in [call control](../concepts/call-control).

| Tool | Arguments | Does |
|---|---|---|
| `scaidial.call.hangup` | `leg_id`, `reason?` | Remove that party |
| `scaidial.call.hold` · `scaidial.call.unhold` | `leg_id` | Hold with music on hold · take off hold |
| `scaidial.call.transfer` | `leg_id`, `to_extension`, `mode?` | `mode: "blind"` (default) transfers that party by SIP REFER. `mode: "attended"` starts a consultation from **your** leg to `to_extension` (extension number or E.164) and returns `{"consult": {"consult_id", "state", …}}` |
| `scaidial.call.transfer_status` | `consult_id` | `ringing`, `talking`, `completed`, `cancelled`, `ended` |
| `scaidial.call.transfer_complete` | `consult_id` | Hand the caller to the target; your leg ends |
| `scaidial.call.transfer_cancel` | `consult_id` | Drop the target; back to the caller |
| `scaidial.call.merge` | `keep_leg_id`, `merge_leg_id` | Merge two of your calls into one conference |
| `scaidial.conference.focus` | `leg_id`, `focus` | `all` join · `kept` split · `<bridge_id>` swap · `none` hold |
| `scaidial.conference.drop` | `leg_id`, `bridge_id` | Hang up one merged call |
| `scaidial.call.speak` | `leg_id`, `text`, `voice_id?`, `language?` | Say text (≤ 1,000 characters) into the call; returns `{"ok": true, "completed": …}` when spoken |

A typical warm handover by a voice agent: `scaidial.call.speak` ("Let me connect you with a colleague"), `scaidial.call.transfer` with `mode: "attended"` from the agent's own leg, brief the colleague once `transfer_status` says `talking`, then `scaidial.call.transfer_complete`.