Skip to content

Connect Your AI Agent (MCP)

The call path — your agent drives the highlighted hop

Your agent drives the highlighted hop: it talks to Parrot Cloud, which runs the call on your line.

This is the chapter Parrot exists for: giving your AI agent a real phone line. Once connected over MCP, an agent like Claude can dial out, answer incoming calls, listen along, whisper course-corrections mid-call, and read back the result — all as ordinary tool calls.

Set it up

Open Devices, click your device, then hit MCP. Choose how to connect:

  • OAuth 2.1 — sign in with your Parrot account and approve the permissions your client needs. The client manages its access tokens. Follow the OAuth 2.1 setup below.
  • API key — create a key for this line and copy your client's configuration. Use the steps and snippets below for this method.

The OAuth option appears when MCP OAuth is enabled on your server.

The per-device MCP page: create a key, copy your client's snippet

  1. Create a key for this line. The page mints an API key bound to this one device. The secret is shown once and dropped straight into the snippets below — copy things from there.
  2. Paste the snippet for your client. The page has a tab per client, already carrying your key and named after your line. Copy from there — the snippets below are the same thing with the values blanked out, so you can see what you're pasting.

That's it. Ask your agent to "call the pharmacy and ask if my prescription is ready" and watch History fill in.

The snippet, client by client

Parrot speaks MCP over Streamable HTTP. For an API-key connection, each snippet supplies the address and Authorization: Bearer <your key> in that client's format. OAuth 2.1 uses the permission-specific URL and browser approval described below; it does not need an API key pasted into these snippets.

claude mcp add --transport http <your-line-name> \
  <your parrot host>/mcp \
  --header "Authorization: Bearer <your key>"

Check it with claude mcp list — your line must show as connected.

~/.codex/config.toml:

[mcp_servers.<your-line-name>]
url = "<your parrot host>/mcp"
http_headers = { Authorization = "Bearer <your key>" }

To keep the secret out of the file, use bearer_token_env_var = "PARROT_API_KEY" instead of http_headers and put the key in that environment variable. Codex dials HTTP itself — it needs no bridge and no Node.js.

~/.gemini/settings.json:

{
  "mcpServers": {
    "<your-line-name>": {
      "type": "http",
      "url": "<your parrot host>/mcp",
      "headers": { "Authorization": "Bearer <your key>" }
    }
  }
}

Keep "type": "http". On older Gemini CLI a bare url meant a different (SSE) transport and the HTTP endpoint was spelled httpUrl, so a snippet copied from another client connects to nothing. Or let the CLI write it: gemini mcp add --transport http <name> <url> -H "Authorization: Bearer <your key>", then gemini mcp list must say Connected.

Any client that speaks Streamable HTTP needs the same three details the console's Other client tab shows:

Transport: Streamable HTTP
URL: <your parrot host>/mcp
Authorization: Bearer <your key>

Here is how a few popular clients spell them.

Cursor and Windsurf

.cursor/mcp.json (or ~/.cursor/mcp.json for every project):

{
  "mcpServers": {
    "<your-line-name>": {
      "url": "<your parrot host>/mcp",
      "headers": { "Authorization": "Bearer <your key>" }
    }
  }
}

Windsurf uses this same shape.

VS Code

.vscode/mcp.json:

{
  "servers": {
    "<your-line-name>": {
      "type": "http",
      "url": "<your parrot host>/mcp",
      "headers": { "Authorization": "Bearer <your key>" }
    }
  }
}

The top-level key is servers, not mcpServers — VS Code quietly ignores the Cursor/Claude spelling, and you get no error, just no tools. From a terminal you can also run code --add-mcp '{"name":"…","type":"http","url":"…","headers":{…}}'.

Zed

settings.json:

{
  "context_servers": {
    "<your-line-name>": {
      "url": "<your parrot host>/mcp",
      "headers": { "Authorization": "Bearer <your key>" }
    }
  }
}

Zed's top-level key is context_servers. Keep the headers for this API-key endpoint. For OAuth, use a permission URL from the Console and follow the browser approval flow.

Claude Desktop and the Claude apps

Claude Desktop, claude.ai and the Claude mobile apps add Parrot as a custom connector (Settings → Connectors → Add custom connector) with the URL alone. There are two ways to authorize it:

  • Sign in (recommended). Paste the connection URL from the device's MCP page (the App or web client tab in OAuth mode) and approve it in your browser. See Sign in instead of pasting a key.
  • Use a key. Enter <your parrot host>/mcp, choose not to sign in, and add the request header Authorization: Bearer <your key>.

No npx mcp-remote bridge and no Node.js are needed. If a guide tells you to wrap Parrot in mcp-remote, it is out of date.

Your own agent (Python)

Writing your own agent? Pass the header to whatever streamable-HTTP MCP client your framework uses:

from mcp.client.streamable_http import streamablehttp_client

streamablehttp_client(
    "<your parrot host>/mcp",
    headers={"Authorization": "Bearer <your key>"},
)

The address works with or without a trailing slash. Assistant editing uses an explicitly approved OAuth connection, described below.

Connecting with a URL

Clients that support MCP sign-in can use the browser approval flow. It is available when the server has MCP OAuth enabled.

Which URL is <your parrot host>?

The hosted console's MCP page fills this in for you — use its snippet verbatim. Self-hosting? The MCP control plane is its own process: in a local dev stack it listens on its own port (http://localhost:7863/mcp on the classic band), while a production deployment routes /mcp on the main host to it — and the server must know its public URL (JASPER_PUBLIC_ORIGIN), or it answers public MCP requests with 421 Misdirected Request. The assistant-authoring surface is the same host with /mcp/assistants appended.

Install the agent skill

Download parrot-phone/SKILL.md — a condensed operating manual for agents, covering outbound and inbound tool loops, the request_info flow, error codes, and retry semantics.

Save the downloaded file as parrot-phone/SKILL.md inside your agent runtime's skills directory, preserving its YAML front matter. Keep the MCP connection configured as above; the skill explains how to use its tools. The download is public and does not require access to the source repository.

OAuth 2.1: sign in instead of pasting a key

OAuth 2.1 lets an MCP client connect with your approval without asking you to create or paste an API key. You sign in on Parrot's page, review the requested access, and approve that client. Parrot uses the authorization-code flow with PKCE S256: the client exchanges a one-use code for tokens and handles renewal. You do not need to paste your account password into the client's configuration.

Connect with OAuth 2.1

  1. On the device's MCP page, choose OAuth 2.1.
  2. Select Calls & history, Create & manage assistants, or both. Review the permission table, which lists the tools and what they can access.
  3. Choose your client and copy its URL or setup commands. The URL changes with your permissions; copy it from the console rather than shortening it to /mcp.
  4. Start sign-in from your client. Check the client name, phone line (if one is included) and account permissions on Parrot's approval page, then select Allow. Return to your client to use the approved tools.

If you change the permissions or phone line later, copy the updated URL and approve a new connection. Editing a URL does not expand an existing token's access.

Paste the console's Copy URL value into the app's MCP server or custom connector settings and choose OAuth sign-in. Do not add an API-key header. This is the setup for compatible custom connectors in ChatGPT, claude.ai and the Claude apps.

Copy the command from the console's Claude Code tab. Its shape is:

claude mcp add --transport http <connection-name> <connection-url>

Open Claude Code, run /mcp, and authenticate that server in your browser.

Copy the commands from the console's Codex tab:

codex mcp add <connection-name> --url <connection-url>
codex mcp login <connection-name>

Complete the sign-in and approval in the browser that opens. These OAuth commands do not need http_headers or bearer_token_env_var.

Choose the permissions and URL

These are paths on your Parrot host. The console supplies the complete URL.

Selected permissions URL path Access you approve
Calls & history /mcp/devices/<device_id>/calls Control that line, read call history across your account, and delete selected finished calls on that line.
Create & manage assistants /mcp/assistants Create, edit and delete saved assistants across your account; no phone control or call-history access.
Both /mcp/devices/<device_id> The calling permissions for that line plus account-wide assistant management.

Calling-only approval does not permit assistant editing. Assistant-only approval does not permit calls. Selecting both grants these two groups, with no automatic access to future permissions. Call deletion does not erase billing or usage.

One calling connection, one line. A second line needs its own device URL and approval. Assistant-only connections have no device binding and can be approved without owning a phone line; their URL is also available on API keys & connected apps.

Renew or revoke a connection

Your client renews access automatically while the approval remains valid. Connected apps appear on API keys & connected apps as "client name (connected app)"; assistant-only access is labeled Account · assistants. Revoke the connection there to stop both access and renewal. The client needs your approval again to reconnect.

Unbinding or transferring a phone line ends its calling or combined approval; rebinding it later requires a new connection. Assistant-only access is independent of device changes. If renewal fails, use your client's sign-in command again and review the permissions before approving.

OAuth 2.1 client compatibility

The client must support MCP authorization over Streamable HTTP, including authorization-server discovery, dynamic client registration and PKCE S256. Clients that only accept a static bearer key can use the API-key setup above for calls and history; assistant editing requires OAuth approval.

For developers connecting an MCP client

Parrot exposes the following OAuth behavior:

  • Discovery: follow resource_metadata in the MCP endpoint's 401 WWW-Authenticate header. The protected-resource document identifies the resource and authorization server. Read that server's /.well-known/oauth-authorization-server metadata for protocol endpoints.
  • Registration: use the advertised dynamic registration endpoint. Client ID Metadata Documents are not supported. Public clients use token_endpoint_auth_method=none; confidential clients can use client_secret_post or client_secret_basic.
  • Authorization: use response_type=code and PKCE with code_challenge_method=S256. Send the matching code_verifier when exchanging the code. Implicit and password grants are not supported.
  • Resource and scope: include the metadata's exact resource URL in authorization and token requests, including refresh requests. The protocol scope is mcp; the resource URL determines the approved permission groups.
  • Requests: send the access token in Authorization: Bearer <access-token> to its approved endpoint. Keep tokens out of URLs and logs.
  • Refresh: use the latest refresh token and replace it after each refresh. Allow only one refresh at a time. Reusing an old refresh token revokes the whole connection, including its latest access token, and requires approval again.
  • Redirects: register an HTTPS callback, or a loopback HTTP callback for a local client. Custom URI schemes are not accepted.

Protocol references: MCP authorization and the OAuth 2.1 authorization framework (IETF draft).

Enable OAuth on a self-hosted server

Enable JASPER_MCP_OAUTH_ENABLED=1 on both the app and MCP processes. Set JASPER_PUBLIC_ORIGIN to the externally reachable app origin. If MCP is reached at a different origin or port, set JASPER_MCP_PUBLIC_ORIGIN to that MCP origin on both processes as well.

Check it's connected — without burning a real call

Three checks, cheapest first, before you ask the agent to dial anything:

  1. The client sees the server. In Claude Code, claude mcp list should show your line's entry as connected. Any client: the tool list should include place_call, get_device_status, get_call_events. A connected entry already proves the key is good — Parrot checks the key while the client connects and refuses the connection if it isn't valid, so there is no such thing as "connected but the key is wrong". A client that shows an authentication error here is telling you the truth; see Troubleshooting for which of 401 / 403 / 503 it is.
  2. The key reaches YOUR line. Ask the agent to run get_device_status() — it reads the line's state without dialing. A healthy, ready line answers with online: true, bt_connected: true, call_state: "idle". If the board is powered but the phone wandered off, you'll see bt_connected: false — the key and server are fine, the Bluetooth side isn't.
  3. (Only if you added /mcp/assistants.) Ask for get_assistant_options() — it lists providers/voices and proves the authoring surface is wired.

No other debugging is worth doing before these three pass.

One key = one phone line

A key gives an agent exactly the device it was created for — there's no tool to list or switch devices. Give an agent two lines by creating two keys and adding two MCP entries. This is deliberate: you always know precisely which phone line an agent can touch.

What your agent can do

The tools, grouped the way an agent uses them:

Tool What it does
Check the line get_device_status Is the line online, idle, ringing, or mid-call right now?
Start a call place_call Dial a number with an objective ("book a table for 4 at 7pm") and a time cap.
answer_call Pick up a ringing inbound call — optionally with a specific assistant chosen for who's calling. An ESP32 board answers every ring itself (hands-free pickup), so there is nothing left for an agent to answer. On Parrot App for Windows automatic answering is a setting that starts off; with it off the line rings until answered, and this tool is how an agent picks up — within the carrier's ring window (~20 s to voicemail).
Supervise it get_call_events The live feed: transcript lines, state changes, and questions the assistant asks you mid-call. It long-polls (~25 s per call) — loop it back-to-back, never sleep between polls.
steer_call Whisper an instruction mid-call — the other party never hears it.
respond_to_request_info Answer the assistant when it needs a fact only you have ("what's the member number?") — within about a minute, or the call proceeds without it.
send_dtmf Press phone-menu keys ("press 2 for pharmacy") — the phone plays real touch-tones into the call over the Hands-Free Profile (HFP) (how DTMF works).
end_call / cancel_call Hang up.
Read the result get_call_result Once ended: outcome, who hung up, full transcript, AI summary. If the assistant defines output fields (set up in the console), extracted carries them — optional and filled shortly after the call; otherwise read the transcript.
get_call_status / list_calls A snapshot of one call / the recent-calls list. get_call_status also returns a resumable events cursor and any pending mid-call question — it's how an agent that restarted picks a live call back up without replaying everything.
Delete history delete_calls Delete 1–100 explicitly selected finished calls belonging to your account on this key's device. Returns successful and failed IDs; retry only failed IDs. Billing retains the usage, credits spent and transactions.
Manage assistants list_assistants / get_assistant / configure_device See the available assistants, inspect one, change which one the line uses by default.

One-off assistants, inline — no saving required. place_call and answer_call accept more than a phone number: objective / context / caller_identity fill the task slots of the line's own assistant, or of the one named by assistant_id (guardrails intact — this is the recommended way), voice and language tweak just those knobs, assistant_id runs a saved assistant (with assistant.template_params to fill its {{variables}} for this call), and assistant={…} lays a full temporary definition (provider, model, voice, opening line, temperature…) over the base for that one call only — nothing is saved, nothing leaks to the next call. system_prompt replaces the entire prompt if you truly want to start from zero. This is why most agents never need the authoring surface at all.

Assistant authoring tools (create / update / delete / get_assistant_options) live on a second endpoint, /mcp/assistants — the full walkthrough is Authoring assistants over MCP. Add it only when you want your agent writing SAVED assistants, not just using them.

Answer mid-call questions explicitly

When the voice agent asks a mid-call question (request_info), it shows up in get_call_events. Every client answers it the same way, with respond_to_request_info(call_id, query_id, answer) — within about a minute, or the call proceeds without it. No client gets a pop-up form.

When a dial is refused — what the agent sees

The same pre-dial guardrails the console applies fire over MCP, as structured errors the agent can route on instead of parsing prose:

Error Meaning Sensible reaction
device_offline The line's bridge isn't connected Report it; a human needs to power the board / reopen the bridge
bt_not_connected Board online, phone out of Bluetooth reach Report it; retrying won't help until the phone is back
device_busy A call is already running (the error names its call_id) Supervise that call or wait for call_ended
insufficient_credits The account's balance can't fund the dial Stop dialing; surface to the owner
daily_call_limit The account hit its per-day call cap Stop dialing; surface to the owner
unknown_assistant assistant_id names no assistant in your account; nothing was dialed Pick an id from list_assistants, or omit it to use the line's assistant
missing_template_params The chosen assistant has a {{variable}} with no value Pass it in assistant.template_params
server_busy / server_draining Transient server condition Brief backoff, then one retry
dial_timeout The phone did not confirm the call in time Check the line's current status before retrying

max_duration_s is required on every place_call and is clamped to the account's ceiling — an agent can never place an unbounded call. After the call, read the deterministic outcome and retryable fields in get_call_result. Some older call records may have no outcome; do not treat a missing result as permission to redial. See Call outcomes and retry rules for the mapping of end reasons, who ended the call, outcomes, and retry rules.

Key management in practice

API keys page: one key per agent, each bound to its line

  • One key = one line for control and deletion. A key controls its bound device and can delete only your finished calls on that device. History reads span your account's devices; they do not expand deletion permissions. Two lines for one agent to control or delete from = two keys = two MCP entries.
  • Deletion is a granted capability. Give a key only to a trusted agent: delete_calls removes selected calls from history and their old links stop working. You cannot restore them from the console. Existing device keys have this capability too; account, payment and provider-key management stay restricted.
  • Two places to mint: the device's MCP page (creates the key AND the client snippet in one step — the fast path) or API keys (the manager's view: every key, its device, when it was last used, revoke buttons).
  • The secret shows once, at creation. There is no re-display; a lost secret means minting a new key.
  • Revoking takes effect within about a minute. Anything the key tries to do — place a call, read a transcript — fails immediately; the connection itself drops on the next check, at most ~60 seconds later. This is the kill switch if a key leaks or an agent misbehaves; the phone line is untouched.
  • Rotation is create-new → update the client config → revoke-old, in that order (zero downtime — both keys work during the overlap).
  • Name keys after their agent ("claude-desktop", "ops-bot") — Billing breaks calls and minutes down by key ID, and the API keys page shows which name each ID belongs to.

What a real errand looks like

A typical agent run, tool call by tool call:

  1. get_device_status() → the line is idle, clear to dial.
  2. place_call(to_number="+1…", max_duration_s=180, objective="Ask if they have a table for 4 tonight at 7; book under Chen if yes.") → returns a call_id.
  3. Loop get_call_events(...) back-to-back — the transcript streams in. The restaurant offers 7:30 instead; the agent sends steer_call("Accept 7:30 if 7:00 isn't available").
  4. The events feed shows the call ended → get_call_result(call_id) → outcome answered, summary: "Table for 4 booked at 7:30pm under Chen."

On an ESP32 board, inbound calls never reach an agent's decision: the board answers every ring itself (hands-free pickup — see Receiving calls), and the agent simply sees the call appear on the events feed. On Parrot App for Windows with Answer incoming calls automatically off, the inbound direction mirrors the outbound one: the agent idles on get_call_events, sees the line start ringing — usually with a caller number attached, though some calls arrive without one — decides whether and how to answer within the carrier's ~20-second ring window, and calls answer_call.

Your agent can be mid-call support, not just a dialer

The request_info flow is the part people miss: if the assistant hits a question it can't answer ("what insurance do you have?"), it asks your agent, which can answer from its context — while the call keeps going.

Authoring assistants over MCP

For a one-off errand, place_call and answer_call accept an inline assistant without saving it.

Reach for the authoring surface when you want your agent to build and keep a reusable, named assistant — a recipe it (or you, or the console) can run again by assistant_id, edit over time, and see in the console's Assistants list. It lives on its own MCP endpoint precisely so its tool schemas don't weigh on every calling session's context.

Connect it

On the device's MCP page, choose OAuth 2.1, tick Create & manage assistants and untick Calls & history (it starts ticked), then approve the generated /mcp/assistants connection. The API keys & connected apps page also has a Copy URL for it. Your ordinary device key does not permit saved-assistant writes. To also control calls, keep both permissions ticked and use the device URL instead.

claude mcp add --transport http parrot-authoring \
  <your parrot host>/mcp/assistants

Open Claude Code, run /mcp, then authenticate this server.

{
  "mcpServers": {
    "parrot-authoring": {
      "url": "<your parrot host>/mcp/assistants"
    }
  }
}

Assistants are account-scoped, so the ones you create here are usable on any line your account owns.

The four tools

Tool What it does
get_assistant_options The valid building blocks: available protocols, providers, and their configuration defaults. Pass protocol (e.g. "ultravox") to also get that protocol's live model, voice, and language choices. Pass provider_id, model, and voice to describe the selection you are editing. Call this first so you build with real values instead of guesses.
create_assistant Save a new reusable assistant under your account. Returns {assistant_id}.
update_assistant Partial edit — only the fields you pass change. A content change appends a new immutable version. Takes effect on the next call.
delete_assistant Delete an unbound assistant. A line's selected assistant remains bound even in Web Phone mode; deleting it is refused (assistant_in_use) until you select another assistant for that line. Historical versions remain available through authorized call records.

The fields

create_assistant and update_assistant share one field set — create needs a name, update needs an assistant_id and changes only what you pass:

Field Meaning
name Display name in the Assistants list.
objective The task in plain language. Provide either this or system_prompt. objective keeps every built-in guardrail (IVR handling, honesty, anti-loop, hang-up) and just fills the goal — prefer it.
system_prompt The entire prompt, replacing all scaffolding. Full control, full responsibility: restate everything yourself.
opening_line The first thing the agent says, when it speaks first.
provider / model / voice The provider to use, model, and voice — validate against get_assistant_options.
language Separate reply and input recognition preferences: {conversation: "zh-CN", recognition: "auto"}. Use IDs from get_assistant_options; auto removes that preference.
first_speaker "agent" (it greets) or "user" (it waits).
temperature Model creativity.
template_params Default values for {{VARIABLES}} used in the prompt; a caller can still override them per call. TODAY and NOW are filled by the server (current local date/time) and are refused here.
icon The icon shown beside it in the console.

A typical authoring run

1. get_assistant_options(protocol="ultravox")
     → the providers, models and voices you can actually use

2. create_assistant(
       name="Dentist reminder",
       objective="Call the patient, confirm tomorrow's 3pm cleaning, and offer
                  to reschedule if they can't make it.",
       provider="ultravox", voice="…", first_speaker="agent")
     → { assistant_id: "asst_…" }

3. later, on the CALLING surface:
   place_call(to_number="+1…", max_duration_s=180, assistant_id="asst_…")

Edits are versioned and non-destructive: update_assistant(assistant_id, voice="…") appends a new version that the next call picks up. A call already running keeps the version it started with — the same freeze-at-call-start rule the console applies when you edit an assistant mid-call.

Inline or saved — which one

Running a recipe once (a specific errand)? Pass it inline to place_call — there's nothing to clean up afterwards. Running it again (a routine your agent repeats, or one you want visible and editable in the console)? Save it here and call it by assistant_id.

Troubleshooting

The client won't connect: 401 Unauthorized

The key is wrong, revoked, or truncated in the client config — the header is missing entirely if you see "no API key on this MCP connection". Keys are shown once at creation, so if in doubt mint a fresh one on the device's MCP page, replace it in the client snippet, and revoke the old one on API keys. Revoking takes effect within about a minute.

The client won't connect: 403 Forbidden

The calling connection requires a key bound to one phone line. Create a key from the device's own MCP page and use its connection instructions.

The client won't connect: 503

That one isn't you. The MCP control plane couldn't reach Parrot's main server; your key is fine. Retry shortly — and if it persists, it's an outage worth reporting.

get_device_status works but place_call is refused

The refusal names its reason — see the error table above. All of these are exactly the checks a console dial runs — fix the underlying one and the agent's dial goes through.

The agent says a tool like list_devices doesn't exist

It doesn't — a key IS the device selection (one key, one line). Point the agent at the current tool set in What your agent can do, or install the agent skill, which describes the real API.

Where this fits

Everything the agent does lands in the same History as your own calls, runs the same assistants, and shows on the same device pages — MCP is a third hand on the same phone, not a separate system.