> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getdial.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getdial.ai/_mcp/server.

# Using Dial from an agent

> How AI agents use Dial: the CLI, the Remote or Local MCP server, or an in-process SDK — and which to choose.

Dial is built for AI agents. There are a few ways to wire it in, and you can mix them in the same project.

## CLI shell-out

If your agent can run shell commands (for example, a coding agent), call the `dial` CLI. Every command accepts `--json`, so the agent gets structured output it can parse instead of prose.

```bash
dial message --to +14155550123 --body "Your code is 123456" --json
```

```json
{ "ok": true, "message": { "id": "msg_...", "status": "queued" } }
```

Why this works well for agents:

* **`--json` on every command** — machine-readable results, no scraping.
* **Stable exit codes** — non-zero means failure, so the agent can branch on success.
* **Blocking waits** — `dial wait-for <event-type>` blocks until a matching event arrives (see [Receive an SMS](/documentation/capabilities/receive-an-sms)).
* **Background capture** — the [listen service](/documentation/cli/listen-service) records events to a local log the agent can tail.

## In-process SDK

If your agent is written in code, import an SDK and call it directly.

```typescript title="Node"
import { DialClient } from "@getdial/sdk";

const dial = new DialClient({ apiKey: process.env.DIAL_API_KEY! });
await dial.sendMessage({ to: "+14155550123", fromNumberId, body: "Hi" });
```

```python title="Python"
from dial_sdk import DialClient, DialConfig

dial = DialClient(DialConfig(api_key="sk_live_..."))
await dial.send_message(to="+14155550123", from_number_id=number_id, body="Hi")
```

```python title="LangChain"
from dial_langchain import SendMessageTool

tools = [SendMessageTool(api_key="sk_live_...")]
# hand `tools` to your LangChain agent
```

## Remote MCP

If your agent speaks the Model Context Protocol, it can skip the CLI and the SDK entirely. Point it at Dial's [Remote MCP](/integrations/tools/mcp) server at `https://getdial.ai/mcp` and authorize once in the browser — no API key handling, no local install. The agent then calls Dial's capabilities as MCP tools (`send_message`, `place_call`, `wait_for_event`, …) that mirror the CLI commands.

## Which should I use?

|                          | CLI                                                                       | Remote MCP                                                         | SDK                                     |
| ------------------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------- |
| **Best when**            | Your agent runs shell commands                                            | Your agent speaks MCP (Claude.ai, Claude Desktop, Cursor, ChatGPT) | Your agent is written in Node or Python |
| **Setup**                | Install `dial`, onboard once                                              | Add one URL, authorize in the browser                              | Install a package, set an API key       |
| **Auth**                 | Local API key (`auth.v1.json`)                                            | OAuth 2.1 in the browser — no key handling                         | API key in code                         |
| **Install footprint**    | Local binary on the machine                                               | Zero install (hosted)                                              | Package dependency                      |
| **Output shape**         | `--json` + stable exit codes                                              | MCP tool results                                                   | Typed return values                     |
| **Waiting for events**   | `dial wait-for` + the [listen service](/documentation/cli/listen-service) | `wait_for_event` tool (long-poll)                                  | Async generators                        |
| **Runs off the machine** | No — local to the machine                                                 | Yes — hosted                                                       | Yes — wherever your code runs           |

On a machine that already has the CLI, `dial mcp` also exposes every command as a **local** MCP server (stdio, reusing the saved key) — see [MCP](/integrations/tools/mcp). It's the same tool surface as the Remote MCP plus enhanced inbound capabilities (a persistent listener, local event fan-out) and onboarding.

All of these call the same REST API and use the same [API key](/documentation/get-started/authentication).