---
title: "MCP server"
description: "Let AI assistants such as Claude, ChatGPT and Cursor send SMS and manage your account over the Model Context Protocol."
---

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

# MCP server

The MessagePort MCP server lets AI clients act on your account on your behalf: sending SMS, managing contacts, subscribing to webhooks, and reading account data. It speaks the [Model Context Protocol](https://modelcontextprotocol.io), so it works with any MCP-compatible client.

## Endpoint

```
https://app.messageport.com.au/mcp
```

It's a remote server using the Streamable HTTP transport, so there's nothing to install or run locally. Point your client at the URL above.

## Authentication

The MCP server uses your existing API key, sent as a bearer token. The token is the key's two parts joined by a single colon:

```
Authorization: Bearer ACCESS_TOKEN:TOKEN_ID
```

1. **Open API Keys**

   Sign in to [MessagePort](https://app.messageport.com.au) and open **Settings** > **API Keys**.
2. **Create a key**

   Create a key for your MCP client. A dedicated key lets you disable MCP access without affecting other integrations.
3. **Build the token**

   Join the **Access Token** and the **Token ID** with a colon, in that order: `ACCESS_TOKEN:TOKEN_ID`. This is the same pair, in the same order, as the username and password for [Basic authentication](/get-started/authentication/).

A missing, malformed or disabled key returns `401 Unauthorized`. The key's last-used time updates as the MCP server uses it, so you can audit MCP activity from the API Keys page.

> **Treat the token like a password**
>
> Anyone with your `ACCESS_TOKEN:TOKEN_ID` string can send messages from your account. Don't paste it into shared config files or commit it to source control. If it leaks, disable the key on the API Keys page.

## What it can do

The server lets your AI client send SMS, check sender IDs and costs, manage contacts, read inbound messages and subscribe to webhooks. Your client discovers the available tools when it connects.

It doesn't cover the whole API. For anything else, such as opt-outs, templates or verification, use the [REST API](/api/).

## Connect a client

Every client needs two things: the endpoint URL, `https://app.messageport.com.au/mcp`, and an `Authorization` header. In the examples below, replace `ACCESS_TOKEN:TOKEN_ID` with your API key's Access Token and Token ID joined by a colon. See [Authentication](#authentication).

### Claude Code

```sh
claude mcp add --transport http sms https://app.messageport.com.au/mcp \
  --header "Authorization: Bearer ACCESS_TOKEN:TOKEN_ID"
```

Run `claude mcp list` to confirm it connected.

### Claude Desktop

Claude Desktop's custom connectors expect OAuth, and this server authenticates with a bearer token instead. Connect through the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge, which needs Node.js.

Open **Settings** > **Developer** > **Edit Config** and add the server to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sms": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.messageport.com.au/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer ACCESS_TOKEN:TOKEN_ID"
      }
    }
  }
}
```

Restart Claude Desktop. The tools appear under the tools menu in a new chat.

### Cursor

Add the server to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

```json
{
  "mcpServers": {
    "sms": {
      "url": "https://app.messageport.com.au/mcp",
      "headers": {
        "Authorization": "Bearer ACCESS_TOKEN:TOKEN_ID"
      }
    }
  }
}
```

### VS Code

Add the server to `.vscode/mcp.json`:

```json
{
  "servers": {
    "sms": {
      "type": "http",
      "url": "https://app.messageport.com.au/mcp",
      "headers": {
        "Authorization": "Bearer ACCESS_TOKEN:TOKEN_ID"
      }
    }
  }
}
```

To keep the token out of a file you might commit, VS Code can prompt for it instead:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "sms-token",
      "description": "MessagePort ACCESS_TOKEN:TOKEN_ID",
      "password": true
    }
  ],
  "servers": {
    "sms": {
      "type": "http",
      "url": "https://app.messageport.com.au/mcp",
      "headers": {
        "Authorization": "Bearer ${input:sms-token}"
      }
    }
  }
}
```

### Other clients

Any MCP client or SDK that supports remote servers over Streamable HTTP can connect. Configure:

| Setting | Value |
|---|---|
| URL | `https://app.messageport.com.au/mcp` |
| Transport | Streamable HTTP |
| Header | `Authorization: Bearer ACCESS_TOKEN:TOKEN_ID` |

If a client only supports local (stdio) servers, use the `mcp-remote` bridge shown under [Claude Desktop](#claude-desktop).

## Troubleshooting

| Symptom | Likely cause |
|---|---|
| `401` when connecting | The `Authorization` header is missing or wrong, or the API key is disabled. Check the header is `Bearer ACCESS_TOKEN:TOKEN_ID`. |
| `Missing or malformed MCP bearer token` | The token has no colon. You probably sent only one part of the key. Send both, joined by a colon. |
| `Invalid MCP credentials` | The two parts don't match an active key, or they're in the wrong order. The Access Token comes first. |
| Send fails on the sender | The sender isn't an approved sender ID for your account. Ask the assistant to list your sender IDs. |
| MMS rejected | MMS must be sent from a dedicated number to an Australian recipient. |
| `Webhook url is invalid` | The URL points at one of our own domains. Use your own endpoint. |
| Tools don't appear | Restart the client after changing its config, and check its MCP logs. In Claude Code, run `claude mcp list`. |
| `429 Too Many Requests` | You've hit the rate limit. See [Limits](#limits). |

## Limits

Requests to the MCP server are rate limited, and share the same per-team limit as the REST API. See [Rate limits](/concepts/rate-limits/).

Sends through the MCP server follow the same rules as the REST API, including [batch, MMS and metadata limits](/guides/sending-messages/).

## Still stuck?

See [Support](/support/) for what to include when you contact us.

Source: https://dev.messageport.com.au/mcp/index.mdx