Skip to content

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.

  • 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.
https://api.sipstack.com/mcp

The server uses the Streamable HTTP transport. It supports MCP protocol revisions up to 2025-11-25, and 2026-07-28.

Send one credential on every request. A request that carries both an API key and an access token is refused with 401.

MethodHowBest 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 keySend 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
  1. Add https://api.sipstack.com/mcp in your client’s connector or MCP settings.
  2. The client opens Switchboard at /oauth/consent, on the page Connect an app. Log in to SIPSTACK if asked.
  3. 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”).
  4. 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.
  5. Click Allow access, or Deny.

The permissions on the consent screen:

ScopeLabel on the consent screenStarts
sms:readRead text messagesTicked
sms:sendSend text messages. Warning: “This app will be able to send text messages from your account.”Unticked
calls:readRead call historyTicked
calls:writePlace calls. Warning: “This app will be able to place calls from your account.”Unticked
numbers:readRead phone numbersTicked
contacts:readRead contactsTicked
aura:readRead Aura setupTicked
aura:writeCreate draft agentsUnticked

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.

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.

These steps are short on purpose: client menus change often. Look for the connector or MCP settings in your client.

  • 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"

Add a connector (developer mode) with the URL https://api.sipstack.com/mcp and choose OAuth. ChatGPT opens the Connect an app page.

Add the server to your Gemini CLI settings.json:

{
"mcpServers": {
"sipstack": {
"httpUrl": "https://api.sipstack.com/mcp",
"headers": {
"X-API-Key": "$SIPSTACK_API_KEY"
}
}
}
}

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.

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>"
}

For a client that only runs local (stdio) servers, bridge with mcp-remote:

Terminal window
# Connect with OAuth (opens your browser; uses a localhost callback)
npx mcp-remote https://api.sipstack.com/mcp
# Or with an API key
npx mcp-remote https://api.sipstack.com/mcp --header "X-API-Key:${SIPSTACK_API_KEY}"

Tools are listed in this order. A client only sees the tools its connection is allowed to use.

ToolWhat it doesScopeReads or writes
account_getSummary 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_listLists Flare SMS messages, newest first. Filter by direction, date range, your number or the other party.sms:readRead
flare_message_getOne Flare SMS message by id: direction, status, numbers, delivery times and any carrier error.sms:readRead
flare_campaigns_listLists Flare SMS campaigns with status, recipient counts and delivery results.sms:readRead
flare_campaign_analyticsResults of one campaign: sent, delivered, failed, queued, replies, opt-outs and link clicks.sms:readRead
nova_calls_listLists Nova PBX calls, newest first: direction, numbers, date, duration and billed seconds.calls:readRead
nova_call_getOne Nova PBX call by id.calls:readRead
nova_voicemails_listLists voicemails: mailbox, caller, length, read or unread, and when it was left.calls:readRead
numbers_listLists the phone numbers on your account with their settings, E911 status and porting status.numbers:readRead
numbers_searchSearches for numbers you can add, by area code or toll-free prefix. Never orders or reserves a number.numbers:readRead
contacts_searchSearches your Flare SMS contacts by name, phone number or email.contacts:readRead
opt_out_checkChecks whether one phone number has opted out of your Flare SMS texts.contacts:readRead
aura_agents_listLists your Aura AI voice agents and the numbers each one answers. Prompts and settings are not returned.aura:readRead
aura_calls_listLists calls handled by your Aura AI agents, with outcome, sentiment and the Aura AI call summary.aura:readRead
aura_get_schemaReads the Aura agent format and authoring guide. No account data.aura:readRead
aura_list_voicesLists the voices your agents can use.aura:readRead
aura_validate_agentChecks an agent file. Never shows a secret and changes nothing.aura:readRead
aura_create_draft_agentSaves an agent as a new inactive draft. Without confirm: true it only previews.aura:writeWrite
flare_sms_sendSends one text message to one US or Canadian number. Preview first.sms:sendWrite
nova_call_originatePlaces one outbound call from one of your Nova PBX extensions to one US or Canadian number. Preview first.calls:writeWrite

Every list returns at most 50 rows per call, and message bodies are cut to 500 characters.

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.

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:

  1. 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 a preview_token.
  2. Confirm. After a person approves the preview, call the tool again with the same arguments plus confirm: true and that preview_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 from first, 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.

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.

  • 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.

  • 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.
Code or reasonHTTPWhat it meansWhat to do
not_enabled404The 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_entitled403Your 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_permitted403The 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_REACHED429”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_REACHED429”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_LIMITED429”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_UNAVAILABLE503”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.

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.