# CallNode MCP server

Your CallNode phone numbers, inside your AI assistant.

CallNode hosts a Model Context Protocol (MCP) server at:

```
https://mcp.callnode.io/mcp
```

Sign in to it from claude.ai, Claude Desktop, ChatGPT, Claude Code, Cursor or VS Code, then tick the numbers the assistant may use. It can then:

- read your call and message history;
- send texts and picture messages;
- call or text your Phone Book contacts by name;
- once you switch calling on, place calls that the CallNode voice agent runs.

The server is hosted by CallNode, so there is nothing to install or run. This repository holds only the connection details: client configs, the registry entry and this README.

- **What it can do, in plain words:** https://callnode.io/integrations/mcp
- **Every tool, permission, limit and error code:** https://callnode.io/docs/mcp

## Before you connect

1. Create an account at https://callnode.io/signup (no credit card to start) and get a number. Self-serve numbers are local and toll-free numbers in the US and Canada.
2. Open **Dashboard → MCP Server**, switch **MCP access** on, and tick the numbers an assistant may use. Every connection shares this one list; a number you did not tick cannot be read from or sent from.

## Connect

You give the client only the server URL. It sends you to the CallNode consent page, and you approve. No token is created, and nothing secret is pasted into a file or a shell.

On the consent page you can untick permissions (sending, for example), choose a live or test connection, and set an hourly send cap. Afterwards the connection appears under **Dashboard → MCP Server**, and you can revoke it there at any time.

### claude.ai and Claude Desktop

1. Open **Settings → Connectors** and choose **Add custom connector**.
2. Enter `https://mcp.callnode.io/mcp` as the server URL and continue. Leave the client id and secret fields empty.
3. Claude opens the CallNode sign-in page. Log in if asked, review the numbers and permissions, and approve.
4. Back in Claude, enable the connector in a chat.

### ChatGPT

1. Enable **Developer mode** under **Settings → Connectors → Advanced**, then choose **Create**.
2. Enter `https://mcp.callnode.io/mcp` as the MCP server URL and pick **OAuth** for authentication. No client id or secret is needed, because ChatGPT registers itself.
3. Approve on the CallNode sign-in page, then add the connector to a chat.

### Claude Code

Either use [`.mcp.json`](.mcp.json) from this repository in your project, or run this once:

```
claude mcp add --transport http callnode https://mcp.callnode.io/mcp
```

Inside Claude Code, type `/mcp`, pick **callnode** and choose **Authenticate**. Approve in the browser.

### VS Code (Copilot agent mode)

1. Save [`.vscode/mcp.json`](.vscode/mcp.json) in your workspace, then start the **callnode** server. VS Code opens the CallNode consent page; approve.
2. In Copilot Chat, choose **Agent** mode and tick the callnode tools.

### Cursor

1. Save [`.cursor/mcp.json`](.cursor/mcp.json) in your project, or the same entry in `~/.cursor/mcp.json`, then reload Cursor.
2. In **Settings → MCP** the server shows **Needs login**. Click it and approve in the browser.

### Without a browser sign-in

For automations where a browser sign-in isn't possible, create a token connection in the dashboard. The snippets for each client are at https://callnode.io/docs/mcp#clients.

## Tools

Each tool is bound to a permission you grant. A connection without that permission does not see the tool at all.

| Tool | Permission | What it does |
|---|---|---|
| `list_numbers` | `numbers:read` | The enabled numbers, with what each can do and whether it has its own voice agent. |
| `get_number` | `numbers:read` | One enabled number. Never webhook addresses, routing or credentials. |
| `list_calls` | `calls:read` | Call records on the enabled numbers, newest first. No transcripts. |
| `get_call` | `calls:read` | One call record, including how it ended. For calls placed through MCP: the summary, outcome and transcript. |
| `place_call` | `calls:place` | Place a call. The CallNode voice agent runs it from your instructions, or the number's own voice webhook does. **Off by default.** |
| `list_messages` | `messages:read` | SMS/MMS history on the enabled numbers. |
| `get_message` | `messages:read` | One message, with its delivery status. |
| `send_message` | `messages:send` | Send a text or picture message, to a number or to a Phone Book contact by name. |
| `list_phone_book` | `phonebook:read` | Your Phone Book: your own lines, with their labels. |
| `add_phone_book_contact` | `phonebook:manage` | Prepares an entry and returns a link. Only you can certify and save it. |
| `remove_phone_book_contact` | `phonebook:manage` | Removes a Phone Book entry. |
| `get_balance` | `account:read` | Your prepaid balance and auto-recharge settings. |
| `get_updates` | `messages:read` | New inbound texts (and calls, when the connection can read calls) since the last check, with an optional wait of up to 20 seconds. |

`send_message` and `place_call` are marked as actions that reach a person and cannot be undone (`destructiveHint`), so clients that honour tool hints ask you before running them.

## Safety and limits

- **Numbers.** Only the numbers you tick are visible, and no token can widen that list.
- **Same rules as the API.** Sends and calls go through the same rules as the CallNode API:
  - opt-outs and STOP replies are honoured;
  - texts and calls fall inside 8am–9pm in the recipient's local time, except your own certified Phone Book lines;
  - sending numbers must be registered for messaging;
  - calls need business verification, and do-not-call lists, destination restrictions and your concurrent-call limit apply;
  - your balance must cover each send.
- **Per-connection limits:**
  - 30 sends an hour by default, settable from 1 to 200;
  - an identical text to the same recipient within 60 seconds is sent once;
  - 10 calls an hour, and the same from/to pair within 60 seconds is never dialled twice;
  - 120 tool calls a minute.
- **The voice agent** introduces itself as an AI assistant calling on behalf of your business and never claims to be human. It cannot transfer a call or take card details.
- **Untrusted content.** Message bodies and caller-supplied text reach the assistant marked as untrusted, so a text that tries to give it instructions reads as data.
- **Activity log.** Every tool call, allowed or refused, appears under Recent activity in your dashboard. Message contents are never stored there.
- **Revoking.** A revoked connection is refused on its next request. A sign-in lapses after 90 days without a fresh one.
- **Test connections** run every rule, then simulate the send or the call. Nothing leaves the platform and nothing is charged.

## Pricing

The MCP server has no fee. Texts and calls are billed from your prepaid balance at your normal rates, and calls the CallNode voice agent runs add a per-minute rate for the voice. All rates are on https://callnode.io/pricing.

## Support

- Help: support@callnode.io
- Security reports: security@callnode.io
- Privacy: https://callnode.io/privacy
- Terms: https://callnode.io/terms
- Security: https://callnode.io/security

## Files in this repository

| File | For |
|---|---|
| [`server.json`](server.json) | The Official MCP Registry entry (`io.callnode/mcp`) |
| [`.mcp.json`](.mcp.json) | Claude Code |
| [`.vscode/mcp.json`](.vscode/mcp.json) | VS Code |
| [`.cursor/mcp.json`](.cursor/mcp.json) | Cursor |

These files are released under the MIT License. The CallNode service itself is covered by the [CallNode Terms](https://callnode.io/terms).