> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fonoster.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Fonoster from an AI client (MCP)

> Connect Claude Desktop or Cursor to your workspace with fonoster-mcp, so the AI client can list your numbers and agents and place calls.

`fonoster-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server for your
workspace. Add it to an AI client such as Claude Desktop or Cursor, and you can ask in plain
words: "Call +1 809 555 0123 from my main number with the Front desk agent." The AI client looks up
your numbers and applications and places the call.

![An AI client such as Claude Desktop or Cursor asks to call +1 809 555 0123 with Front desk. It talks to fonoster-mcp on your computer over MCP (stdio); fonoster-mcp offers list\_numbers, list\_applications, create\_call and create\_call\_batch and calls the Fonoster API with your API key. Fonoster places the outbound call, and the Front desk agent handles it.](https://mintcdn.com/fonoster/GsxtawNPYOQvohG4/images/mcp/flow-light.png?fit=max\&auto=format\&n=GsxtawNPYOQvohG4\&q=85\&s=c5b17e974b2b90e69e7dce72f263015b)

> [!NOTE]
>
> This page is about controlling Fonoster from an AI client. It isn't a way to give an Autopilot
> agent MCP tools: agents run [built-in and HTTP tools](https://docs.fonoster.com/autopilot/tools.md) only.

## Before you begin

You need:

* An API key and your workspace access key ID (`WO…`). See
  [Workspaces, members and API keys](https://docs.fonoster.com/workspace/access.md).
* A number in your workspace to call from. See [Numbers and routing](https://docs.fonoster.com/telephony/numbers.md).
* An Autopilot agent or a stream to handle the calls.
* [Node.js](https://nodejs.org/) 22 or later. The AI client starts the server with `npx`.

> [!WARNING]
>
> The server signs in with an API key, which has full access to the workspace. Anything you ask the
> AI client to do, it can do, including calling many numbers. Use it only with numbers you have
> consent to call.

## Connect your AI client

**Claude Desktop (CLI)**

If you use the `fonoster` CLI, it can write Claude Desktop's configuration for you. Log in to
the workspace first:

```bash theme={"system"}
fonoster workspaces:login
```

Then add the Fonoster server to Claude Desktop with the active workspace's login:

```bash theme={"system"}
fonoster mcp:configure
```

It prints:

```text theme={"system"}
MCP client configured successfully for workspace: Acme Support
```

To use another workspace you're logged in to, pass its ref with `--workspace`. The command
works on macOS and Windows, and keeps any other servers already in the file.

Restart Claude Desktop to load the server.

**Claude Desktop (manual)**

Open `claude_desktop_config.json`:

* macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
* Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Add `fonoster` under `mcpServers`, with your workspace access key ID, API key ID and secret:

```json claude_desktop_config.json theme={"system"}
{
  "mcpServers": {
    "fonoster": {
      "command": "npx",
      "args": ["-y", "@fonoster/mcp@latest"],
      "env": {
        "MCP_WORKSPACE_ACCESS_KEY_ID": "WO7d2kq9x4m1c8b3n6p0r5t2v9y4z7a1e3",
        "MCP_APIKEY_ACCESS_KEY_ID": "APk3n8q2w7e5r1t9y4u6i0o3p8a2s5d7f1",
        "MCP_APIKEY_ACCESS_KEY_SECRET": "<your secret>"
      }
    }
  }
}
```

Restart Claude Desktop to load the server.

**Cursor**

Open Cursor's MCP configuration, `~/.cursor/mcp.json` for every project or `.cursor/mcp.json`
in one project. Add `fonoster` under `mcpServers`:

```json mcp.json theme={"system"}
{
  "mcpServers": {
    "fonoster": {
      "command": "npx",
      "args": ["-y", "@fonoster/mcp@latest"],
      "env": {
        "MCP_WORKSPACE_ACCESS_KEY_ID": "WO7d2kq9x4m1c8b3n6p0r5t2v9y4z7a1e3",
        "MCP_APIKEY_ACCESS_KEY_ID": "APk3n8q2w7e5r1t9y4u6i0o3p8a2s5d7f1",
        "MCP_APIKEY_ACCESS_KEY_SECRET": "<your secret>"
      }
    }
  }
}
```

Don't commit a project's `mcp.json` with the secret in it.

### Settings

The server reads these environment variables:

| Variable | Required | What it is |
| - | - | - |
| `MCP_WORKSPACE_ACCESS_KEY_ID` | Yes | Your workspace access key ID, `WO…`. |
| `MCP_APIKEY_ACCESS_KEY_ID` | Yes | The API key ID, `AP…`. |
| `MCP_APIKEY_ACCESS_KEY_SECRET` | Yes | The API key secret. |
| `MCP_ENDPOINT` | No | The API address. Defaults to Fonoster Cloud, `api.fonoster.ai`. |
| `MCP_ALLOW_INSECURE` | No | `true` to connect without TLS, for a local install. Defaults to `false`. |

On your own install, add `MCP_ENDPOINT` with your API's address. `mcp:configure` doesn't write it,
so add it to the file by hand.

## Check it works

In the AI client, ask: "List my Fonoster numbers." It uses the `list_numbers` tool and answers
with your numbers. If it can't start the server or sign in, check the three IDs, and that the key
hasn't expired or been deleted.

## Place a call

Ask for the call in plain words, with the number in E.164 format:

```text theme={"system"}
Call +18095550123 from +18095550100 using the Front desk agent.
```

The AI client finds the agent's ref with `list_applications`, then uses `create_call`. Fonoster
dials the number, and the agent or stream you named handles the call. The AI client answers with
the call's ref, such as `Call created with REF: 3f6b1d8e-2a4c-4e9f-8b71-5c0d9e2a6f13`. Find the call
under **Calls** in the dashboard.

To call a list of numbers, ask for a batch:

```text theme={"system"}
Call +18095550123, +18095550124 and +18095550125 from +18095550100
with the Front desk agent, 10 calls per minute.
```

The AI client uses `create_call_batch`. It answers right away, and the calls go out one by one in
the background at the rate you asked for (20 per minute by default).

> [!WARNING]
>
> A batch runs inside the MCP server on your computer. If you quit the AI client before the batch
> ends, the remaining calls aren't made. The AI client isn't told when a call in a batch fails:
> check **Calls** in the dashboard.

For larger campaigns, place calls from your own code. See
[Make outbound calls](https://docs.fonoster.com/telephony/outbound-calls.md).

The `fonoster mcp:configure` command and its flags are in the
[CLI reference](https://docs.fonoster.com/reference/cli.md#mcp).

## Tools

| Tool | Inputs | What it does |
| - | - | - |
| `list_numbers` | `page_size`, `page_token` (optional) | Lists the workspace's numbers: ref, name and number. |
| `list_applications` | `page_size`, `page_token` (optional) | Lists Autopilot agents (`AUTOPILOT`) and streams (`STREAM`): ref, name, type and dates. |
| `create_call` | `from`, `to`, `app_ref`; optional `timeout`, `metadata` | Places one call and returns its ref. |
| `create_call_batch` | `from`, `to_array`, `app_ref`; optional `timeout`, `metadata`, `calls_per_minute` | Places calls to every number in `to_array`, `calls_per_minute` apart (1 to 60, default 20). |

For both call tools:

* `from` is a number in your workspace, in E.164 format, such as `+18095550100`.
* `to` is an E.164 number, a SIP user or a `sip:` URI.
* `app_ref` is the ref of the agent or stream that handles the call.
* `timeout` is how many seconds to ring before giving up, up to 120. It defaults to 30.
* `metadata` is a JSON object passed to your application with the call.

The server also offers one prompt, `create_call_prompt`. It walks the AI client through a call
step by step: ask for the numbers to call, offer your numbers to call from, pick the application,
confirm the details, then place the call. In Claude Desktop, pick it from the prompts menu.

## What it can't do yet

The server only lists numbers and applications and places calls. It can't create or change
agents, numbers or other resources, read call records, or hang up a call.

## Next steps

> **[Make outbound calls](https://docs.fonoster.com/telephony/outbound-calls.md)**
>
> Place calls from your own code with the SDK.

> **[Build an Autopilot agent](https://docs.fonoster.com/autopilot/build-an-agent.md)**
>
> Write the agent that handles the calls.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.