Book a demo
Book a demo (877) 300-0016

Developers · PhoneIQ MCP Server

Control your voice agents from any AI tool.

The PhoneIQ MCP server connects Claude, ChatGPT, Cursor, Replit or any MCP client to your PhoneIQ account. Add one URL, sign in with PhoneIQ and pick your workspace. Your AI tool can then read calls and transcripts, and draft and deploy your agents. An API key works too.

Request access Connect a client

What it is

An MCP server over the PhoneIQ customer API.

MCP is the open standard for connecting AI assistants to business tools. The PhoneIQ MCP server speaks it over streamable HTTP and forwards each request to the PhoneIQ customer API. When you sign in with PhoneIQ, it creates an API key for that one connection in your workspace. If you paste your own API key instead, it uses that. Either way, your AI tool sees exactly what that key can see.

  • Read your calls

    Recent calls with outcomes, full transcripts as Caller and Agent turns, private recording links, and monthly minutes.

  • Configure your agents

    Draft new agents with a greeting and instructions, review every saved version, and deploy the one you want live.

  • Wire up events

    Send call, transcript and recording events to your app or CRM with signed webhooks, and test them on the spot.

Control your agent

Draft, review, deploy. In plain words.

Your AI tool works through the same steps you would. New agents start as drafts and never answer calls on create. Deploying makes a saved version live, so you can roll forward to a new version or back to an earlier one.

  • Draft and review

    "Draft a Saturday agent called Weekend Desk. It should say we close at 2pm on Saturdays and take a message. Show it to me before it goes live."

    • create_agent_draft with a name, greeting and instructions
    • get_agent to show the greeting, instructions and versions

  • Deploy

    "Looks right. Deploy Weekend Desk."

    • deploy_agent_version makes the latest saved version live and switches the draft to active
    • It answers calls once a phone number is routed to it in PhoneIQ

  • Roll forward or back

    "Version 4 of the front desk agent is the one we tested. Make it live."

    • list_agents and get_agent to find the agent and its saved versions
    • deploy_agent_version with version: 4

  • Check the setup

    "Which number goes to which agent, and what does the front desk agent say when it answers?"

    • list_routes for each number and the agent it reaches
    • get_agent for the greeting and instructions

Not in the MCP server yet: editing an existing agent, choosing a voice or model (new agents use your account defaults), and changing which number goes to which agent. Routes are read only here.

Tool reference

12 tools, one connection.

Results come back as short text your AI tool can read: names, numbers, outcomes and transcripts. List tools return a before cursor when there are more results. Inputs marked optional can be left out.

Read

  • list_agents

    Your voice agents, newest first, with status and live version.

    Inputs: status (draft, active or archived, optional), limit (1 to 200), before

  • get_agent

    One agent: status, live and draft versions, engine, greeting, instructions and enabled tools.

    Inputs: agent_id

  • list_routes

    Which phone number goes to which agent, with recording settings.

    Inputs: limit (1 to 500), before

  • get_usage

    Calls and minutes for a month, with your monthly cap if one is set.

    Inputs: period (YYYY-MM, optional, defaults to this month), granularity (kind or day)

Agent configuration

  • create_agent_draft

    Create a new agent as a draft. It does not answer calls until it is deployed and a number is routed to it.

    Inputs: name, greeting, instructions, description (optional)

  • deploy_agent_version

    Make a saved version live. Without a version, deploys the latest one. A draft agent is switched to active.

    Inputs: agent_id, version (optional)

Calls

  • list_calls

    Recent calls, newest first: numbers, time, duration, outcome and agent.

    Inputs: agent_id (optional), since (ISO time, optional), limit (1 to 200), before

  • get_call

    One call with its outcome and full transcript as Caller and Agent turns.

    Inputs: call_id

  • get_recording_link

    A private download link for a call recording. Downloading it needs your PhoneIQ key; no public link is created.

    Inputs: call_id

Webhooks

  • create_webhook

    Subscribe an HTTPS endpoint to events. Returns the signing secret once.

    Inputs: url (https), events (list, or * for all), description (optional)

  • list_webhooks

    Your webhook endpoints with their events and delivery health.

    Inputs: none

  • test_webhook

    Send one webhook.test event now and report whether it was accepted.

    Inputs: webhook_id

Auth and safety

One workspace, one key, until you revoke it.

Sign in with PhoneIQ

  • Your AI tool opens a PhoneIQ page that names the app asking for access. An app that registered itself is marked as unverified, so check the name before you approve.
  • You log in to PhoneIQ and pick the workspace. Only a workspace owner or admin can approve a connection.
  • PhoneIQ creates one API key for that connection, named MCP · app · host, and lists it in Settings, API keys.
  • The connection does not expire. It lasts until you revoke that key in Settings, API keys, or disconnect PhoneIQ in your AI tool.
  • Connecting the same app to the same workspace again replaces its old key.

Or your own API key

  • An account owner or admin creates a key in PhoneIQ under Settings, API keys. It is shown once.
  • Send it on every request: Authorization: Bearer YOUR_API_KEY.
  • Each key belongs to one PhoneIQ account and sees only that account.
  • Revoke it anytime in the same place, and it stops working.
  • The MCP server never stores, logs or shows your key.

What a connection can do

  • There is one access level today, with no read-only option. A connection can read calls, transcripts and recordings, and it can also create and deploy agents and create webhooks.
  • Only a fixed list of customer API operations is reachable. Ops, partner and internal routes are not.
  • Requests are rate limited. Over the limit you get HTTP 429 with a retry-after header.
  • New agents start as drafts and never go live on create.

Connect

Add PhoneIQ to your AI tool.

Early access. The MCP server is enabled per account during early access. Request access to get enabled, then use the settings below.

Recommended

Sign in with PhoneIQ

Add the URL with no headers. Your AI tool finds PhoneIQ's sign-in by itself and registers itself, so there is nothing to set up first. When it asks, sign in to PhoneIQ, pick your workspace and approve.

URL        https://mcp.agents.phoneiq.co/mcp
Transport  Streamable HTTP
Headers    none

Under the hood this is OAuth 2.1 with dynamic client registration and client ID metadata documents. A request without credentials gets a 401 that points your client to PhoneIQ's sign-in.

Claude

  1. Go to Customize, then Connectors.
  2. Click + Add, then Add custom connector.
  3. Name it PhoneIQ, paste the URL and click Continue.
  4. Keep the sign-in settings Claude detects, and click Add.
  5. Connect, then sign in to PhoneIQ and pick your workspace.

ChatGPT

  1. Go to chatgpt.com/plugins.
  2. Select the plus button, then Add custom MCP server.
  3. Enter a name and description, and paste the URL under Connection.
  4. Choose OAuth for authentication, review the warning and select Create as a plugin.
  5. Sign in to PhoneIQ when asked.

Your ChatGPT workspace's settings may need to allow custom MCP servers.

Cursor

Add this to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every project. Cursor reads PhoneIQ's sign-in details and asks you to sign in.

{
  "mcpServers": {
    "phoneiq": {
      "url": "https://mcp.agents.phoneiq.co/mcp"
    }
  }
}

Claude Code

Run this once in your terminal.

claude mcp add --transport http phoneiq \
  https://mcp.agents.phoneiq.co/mcp

Then sign in: run /mcp in Claude Code and choose phoneiq, or run claude mcp login phoneiq.

Replit Agent

  1. Open Integrations, then MCP Servers.
  2. Click + Add MCP server and name it PhoneIQ.
  3. Paste the URL. Leave the headers empty.
  4. Click Test & save. Replit walks you through signing in to PhoneIQ.

Or connect with an API key

Use this for scripts and clients that cannot open a browser to sign in. Create a key in PhoneIQ under Settings, API keys, and send it as a header.

Any MCP client

URL        https://mcp.agents.phoneiq.co/mcp
Transport  Streamable HTTP
Header     Authorization: Bearer YOUR_API_KEY

To try it by hand, run npx @modelcontextprotocol/inspector, choose Streamable HTTP, paste the URL and add the header.

Claude Code, Cursor and Replit

claude mcp add --transport http phoneiq \
  https://mcp.agents.phoneiq.co/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

In Cursor, add "headers": { "Authorization": "Bearer YOUR_API_KEY" } next to the URL. In Replit, open Advanced settings when you add the server and add a header named Authorization with the value Bearer YOUR_API_KEY.

Webhooks

Call events, straight to your app or CRM.

What you can receive

PhoneIQ sends an HTTPS POST to your endpoint as things happen. Subscribe to any of these events, or to all of them:

  • call.created, call.answered, call.ended, call.failed
  • transcript.final and recording.ready
  • usage.call_summary and contact.erased
  • webhook.test for checking your endpoint

Every delivery is signed. Verify the x-phoneiq-signature header (HMAC-SHA256) with the signing secret you get once when you create the webhook. Delivery is at least once, so dedupe on the event id.

Set one up by asking

"Add a webhook to https://your-app.example.com/phoneiq for call.ended and transcript.final, send a test event, and tell me if it arrived."

  • create_webhook returns the endpoint and its signing secret
  • test_webhook sends a test event and reports the result

Every delivery looks like this

{
  "id": "evt_...",
  "type": "call.ended",
  "apiVersion": "2026-06",
  "createdAt": "2026-06-13T17:42:08.114Z",
  "customerId": "cust_...",
  "data": { }
}

Build on PhoneIQ.

Tell us what you're building and which AI tool you use. We'll get your account enabled.

Or email saliba@phoneiq.co.

Request access