SIPSTACK MCP Server
SIPSTACK MCP Server
Section titled “SIPSTACK MCP Server”The SIPSTACK MCP server connects an AI assistant to your SIPSTACK account through the Model Context Protocol (MCP). Once connected, an assistant such as Claude or ChatGPT can read your Flare SMS messages and campaigns, your Nova PBX call history and voicemail details, your phone numbers and contacts, and your Aura AI agents and their call summaries. When the send tools are turned on, it can also send one text message or place one call at a time, each only after a preview step.
The assistant only ever works on the account that connected it.
Requirements
Section titled “Requirements”- A plan that includes API access: Flare SMS Pro or higher, or Nova PBX Pro or higher. A Nova PBX Core account is refused with: “API and app connections require Flare or Nova Pro or higher. Upgrade your plan to connect an app.”
- Not in HIPAA mode. The MCP server is off for organizations in HIPAA mode.
- To connect an app or create a key: the Manage API Keys & Webhooks permission (account owners always have it). See API Keys.
The Server Address
Section titled “The Server Address”https://api.sipstack.com/mcpThe server uses the Streamable HTTP transport. It supports MCP protocol revisions up to 2025-11-25, and 2026-07-28.
Two Ways to Authenticate
Section titled “Two Ways to Authenticate”Send one credential on every request. A request that carries both an API key and an access token is refused with 401.
| Method | How | Best for |
|---|---|---|
| Connect an app (OAuth) | Add the server address to your client. It opens SIPSTACK and you choose what the app may do. | Claude, ChatGPT, and clients that receive the OAuth callback on localhost |
| API key | Send a SIPSTACK API key as X-API-Key: <key> or Authorization: Bearer <key>. | Command-line tools, server-side agents, and clients that cannot complete the OAuth connection |
Connect an App (OAuth)
Section titled “Connect an App (OAuth)”- Add
https://api.sipstack.com/mcpin your client’s connector or MCP settings. - The client opens Switchboard at
/oauth/consent, on the page Connect an app. Log in to SIPSTACK if asked. - Check the details before you choose:
- App requesting access: the name the app gave. SIPSTACK has not verified who made it.
- After you choose, you will be sent to: only allow access if you recognise this address and you started the connection yourself.
- Account this app will have access to: access is for the account you are logged in to, never your other accounts. If you belong to several, switch to the right one first.
- Connects to: SIPSTACK (“Your SIPSTACK account, including Flare SMS, Nova PBX and Aura AI”).
- Under This app will be able to, tick only what the app needs. Read permissions start ticked. Permissions that send something or create something start unticked.
- Click Allow access, or Deny.
The permissions on the consent screen:
| Scope | Label on the consent screen | Starts |
|---|---|---|
sms:read | Read text messages | Ticked |
sms:send | Send text messages. Warning: “This app will be able to send text messages from your account.” | Unticked |
calls:read | Read call history | Ticked |
calls:write | Place calls. Warning: “This app will be able to place calls from your account.” | Unticked |
numbers:read | Read phone numbers | Ticked |
contacts:read | Read contacts | Ticked |
aura:read | Read Aura setup | Ticked |
aura:write | Create draft agents | Unticked |
An app never receives full access (*), and the access it receives works only at https://api.sipstack.com/mcp.
OAuth connections are accepted from Claude, ChatGPT, Google, and clients that use a localhost callback. For any other client, use an API key.
Use an API Key
Section titled “Use an API Key”Create an API key in Switchboard at Account → Integrations → API keys and send it as X-API-Key: <key> or Authorization: Bearer <key>.
- Read tools accept a key that holds the tool’s scope, or a full-access
*key. - Write tools (
flare_sms_send,nova_call_originate,aura_create_draft_agent) need their scope listed on the key. A full-access*key can use read tools only over MCP.
The same scopes also work in the SIPSTACK REST API, where they can do more. For example, sms:send on a key also sends Flare SMS campaigns over REST. Create a separate key for your MCP client and give it only the scopes it needs.
A sandbox key (sk_test_…) works too. With a sandbox key, the send tools and aura_create_draft_agent are simulated: nothing is sent or created, and the daily limits still count.
Set Up Your Client
Section titled “Set Up Your Client”These steps are short on purpose: client menus change often. Look for the connector or MCP settings in your client.
Claude
Section titled “Claude”-
Claude apps: add a custom connector with the URL
https://api.sipstack.com/mcp. Claude opens the Connect an app page. -
Claude Code, connecting with OAuth:
Terminal window claude mcp add --transport http sipstack https://api.sipstack.com/mcp -
Claude Code, with an API key:
Terminal window claude mcp add --transport http sipstack https://api.sipstack.com/mcp \--header "X-API-Key: $SIPSTACK_API_KEY"
ChatGPT
Section titled “ChatGPT”Add a connector (developer mode) with the URL https://api.sipstack.com/mcp and choose OAuth. ChatGPT opens the Connect an app page.
Gemini CLI
Section titled “Gemini CLI”Add the server to your Gemini CLI settings.json:
{ "mcpServers": { "sipstack": { "httpUrl": "https://api.sipstack.com/mcp", "headers": { "X-API-Key": "$SIPSTACK_API_KEY" } } }}Microsoft Copilot Studio
Section titled “Microsoft Copilot Studio”Add an MCP tool with the server URL https://api.sipstack.com/mcp and choose API key authentication, sent in the X-API-Key header. Connecting Copilot Studio with OAuth isn’t supported yet.
xAI API
Section titled “xAI API”Add SIPSTACK as a remote MCP tool in your request. Set server_url to https://api.sipstack.com/mcp and pass your SIPSTACK API key as the tool’s bearer token (authorization):
{ "type": "mcp", "server_label": "sipstack", "server_url": "https://api.sipstack.com/mcp", "authorization": "<your SIPSTACK API key>"}Any Other Client (mcp-remote)
Section titled “Any Other Client (mcp-remote)”For a client that only runs local (stdio) servers, bridge with mcp-remote:
# Connect with OAuth (opens your browser; uses a localhost callback)npx mcp-remote https://api.sipstack.com/mcp
# Or with an API keynpx mcp-remote https://api.sipstack.com/mcp --header "X-API-Key:${SIPSTACK_API_KEY}"The Tools
Section titled “The Tools”Tools are listed in this order. A client only sees the tools its connection is allowed to use.
| Tool | What it does | Scope | Reads or writes |
|---|---|---|---|
account_get | Summary of the connected account: name, status, timezone, products, plan names and whether API access is on. Never billing or payment details. | None (any connection) | Read |
flare_messages_list | Lists Flare SMS messages, newest first. Filter by direction, date range, your number or the other party. | sms:read | Read |
flare_message_get | One Flare SMS message by id: direction, status, numbers, delivery times and any carrier error. | sms:read | Read |
flare_campaigns_list | Lists Flare SMS campaigns with status, recipient counts and delivery results. | sms:read | Read |
flare_campaign_analytics | Results of one campaign: sent, delivered, failed, queued, replies, opt-outs and link clicks. | sms:read | Read |
nova_calls_list | Lists Nova PBX calls, newest first: direction, numbers, date, duration and billed seconds. | calls:read | Read |
nova_call_get | One Nova PBX call by id. | calls:read | Read |
nova_voicemails_list | Lists voicemails: mailbox, caller, length, read or unread, and when it was left. | calls:read | Read |
numbers_list | Lists the phone numbers on your account with their settings, E911 status and porting status. | numbers:read | Read |
numbers_search | Searches for numbers you can add, by area code or toll-free prefix. Never orders or reserves a number. | numbers:read | Read |
contacts_search | Searches your Flare SMS contacts by name, phone number or email. | contacts:read | Read |
opt_out_check | Checks whether one phone number has opted out of your Flare SMS texts. | contacts:read | Read |
aura_agents_list | Lists your Aura AI voice agents and the numbers each one answers. Prompts and settings are not returned. | aura:read | Read |
aura_calls_list | Lists calls handled by your Aura AI agents, with outcome, sentiment and the Aura AI call summary. | aura:read | Read |
aura_get_schema | Reads the Aura agent format and authoring guide. No account data. | aura:read | Read |
aura_list_voices | Lists the voices your agents can use. | aura:read | Read |
aura_validate_agent | Checks an agent file. Never shows a secret and changes nothing. | aura:read | Read |
aura_create_draft_agent | Saves an agent as a new inactive draft. Without confirm: true it only previews. | aura:write | Write |
flare_sms_send | Sends one text message to one US or Canadian number. Preview first. | sms:send | Write |
nova_call_originate | Places one outbound call from one of your Nova PBX extensions to one US or Canadian number. Preview first. | calls:write | Write |
Every list returns at most 50 rows per call, and message bodies are cut to 500 characters.
Text From Other People Is Untrusted
Section titled “Text From Other People Is Untrusted”Message bodies, contact names, caller names, call and Aura summaries, agent names and number labels are written by other people. The server wraps them in UNTRUSTED_* tags and tells the assistant to treat them as information only, never as instructions.
Sending a Text or Placing a Call
Section titled “Sending a Text or Placing a Call”flare_sms_send and nova_call_originate are off until SIPSTACK turns them on. While they are off, they don’t appear in the tool list.
Both tools work in two steps:
- Preview. Call the tool without
confirm. Nothing is sent or dialed. Every check runs, and the result shows what would happen: the recipient and from-number (and segment count) for a text, or the extension and destination for a call, plus how much of today’s limit is used, and apreview_token. - Confirm. After a person approves the preview, call the tool again with the same arguments plus
confirm: trueand thatpreview_token. Every check runs again.
The preview_token works once and expires after 15 minutes. It is tied to the tool, the account, the arguments and the credential. If anything changes, run the preview again.
Other rules:
- One recipient per call. The number must be a US or Canadian phone number (10 digits, or 11 starting with 1). Other countries are refused.
- Emergency numbers can’t be called.
- Texts go out from your Flare SMS number (or the one you name in
from). Opted-out or blocked recipients, unregistered US sending and plan limits are refused, exactly as in the REST API. - Calls ring the Nova PBX extension you name in
fromfirst, then dial the number when it answers. - Usage is billed the same way as a text or call made any other way on your plan.
Daily Limits
Section titled “Daily Limits”Each organization can send up to 200 text messages and place up to 50 calls a day through the MCP server. The day is the UTC day: the count resets at 00:00 UTC. SIPSTACK support can raise or lower these limits for your organization on request.
Calls placed through the MCP server also count toward the account’s limit of 10 calls a minute.
If a limit can’t be checked, the send is refused and nothing is sent.
What the Server Never Does
Section titled “What the Server Never Does”- Send Flare SMS campaigns, order phone numbers or change E911 addresses.
- Create or change webhooks, run integration actions, opt a contact in, or delete anything.
- Activate, edit or delete an Aura AI agent. New agents are only saved as inactive drafts, and a person on your team activates them in Switchboard. Each organization can create up to 20 drafts per hour.
- Return call recordings, voicemail audio or call transcripts. Tools return call details and call and Aura AI summaries only.
- Generate speech or voices.
- See passwords, API keys or any other credentials.
- Work on any account other than the one the credential belongs to. Tool arguments that name an organization are refused.
SIPSTACK keeps an audit record of every tool call, whether it was allowed or refused. Message text is never recorded in it.
Revoking Access
Section titled “Revoking Access”- OAuth connections are listed in Switchboard under Account → Integrations → API keys → Connected apps, with who connected each app, when, and whether it connected to SIPSTACK or Aura AI. Click Revoke access to disconnect an app. It is disconnected straight away. Anything it already created, such as draft Aura AI agents, stays in your account.
- API keys: revoke or delete the key on the same API keys page.
Errors
Section titled “Errors”| Code or reason | HTTP | What it means | What to do |
|---|---|---|---|
not_enabled | 404 | The MCP server isn’t turned on for your organization, or the send tools aren’t turned on. Also returned for organizations in HIPAA mode. | During the preview, request Preview access in Switchboard under Integrations → API keys. For the send tools, contact SIPSTACK support. |
not_entitled | 403 | Your plan doesn’t include API access: “API and app connections require Flare or Nova Pro or higher. Upgrade your plan to connect an app.” | Upgrade your plan. |
not_permitted | 403 | The connection doesn’t have the tool’s scope, or a full-access * key called a write tool. | Reconnect and tick the permission, or use a key with the scope listed on it. |
| (both credentials sent) | 401 | ”Send one credential: an API key or an access token, not both.” | Send one credential. |
MCP_DAILY_SMS_CAP_REACHED | 429 | ”Daily SMS limit reached for this account. Contact support to raise it.” | Wait for the next UTC day (see Retry-After), or contact support. |
MCP_DAILY_CALL_CAP_REACHED | 429 | ”Daily call limit reached for this account. Contact support to raise it.” | Wait for the next UTC day (see Retry-After), or contact support. |
MCP_CALL_RATE_LIMITED | 429 | ”Too many calls from this account in the last minute. Wait a minute and try again.” | Wait a minute (see Retry-After). |
MCP_SEND_CAP_UNAVAILABLE | 503 | ”The daily sending limit could not be checked right now; nothing was sent.” | Try again in a moment. |
| Connection request not found (consent page) | — | The connection request expired or was already used. | Start the connection again from your app. |
| You do not have permission to connect apps (consent page) | — | You don’t have the Manage API Keys & Webhooks permission. | Ask an account owner or admin to grant it, or to connect the app themselves. |
If a send result says “The message could not be confirmed as sent” or “The call could not be confirmed as placed”, check the message or call history before trying again.
The Aura AI MCP Server
Section titled “The Aura AI MCP Server”An Aura-only server is still available at https://api.sipstack.com/mcp/aura. It has the four aura_* authoring tools only (aura_get_schema, aura_list_voices, aura_validate_agent, aura_create_draft_agent) and the scopes aura:read and aura:write. It is turned on separately, and its consent screen shows Connects to: Aura AI (“Aura AI voice agents only”).
Access granted for one server doesn’t work at the other. To use both, connect each one.