Connect Your AI Agent (MCP)

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.

- 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.
- 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 headerAuthorization: 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
- On the device's MCP page, choose OAuth 2.1.
- Select Calls & history, Create & manage assistants, or both. Review the permission table, which lists the tools and what they can access.
- 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. - 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_metadatain the MCP endpoint's401WWW-Authenticateheader. The protected-resource document identifies the resource and authorization server. Read that server's/.well-known/oauth-authorization-servermetadata 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 useclient_secret_postorclient_secret_basic. - Authorization: use
response_type=codeand PKCE withcode_challenge_method=S256. Send the matchingcode_verifierwhen exchanging the code. Implicit and password grants are not supported. - Resource and scope: include the metadata's exact
resourceURL in authorization and token requests, including refresh requests. The protocol scope ismcp; 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:
- The client sees the server. In Claude Code,
claude mcp listshould show your line's entry as connected. Any client: the tool list should includeplace_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 of401/403/503it is. - 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 withonline: true,bt_connected: true,call_state: "idle". If the board is powered but the phone wandered off, you'll seebt_connected: false— the key and server are fine, the Bluetooth side isn't. - (Only if you added
/mcp/assistants.) Ask forget_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

- 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_callsremoves 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:
get_device_status()→ the line isidle, clear to dial.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 acall_id.- Loop
get_call_events(...)back-to-back — the transcript streams in. The restaurant offers 7:30 instead; the agent sendssteer_call("Accept 7:30 if 7:00 isn't available"). - The events feed shows the call ended →
get_call_result(call_id)→ outcomeanswered, 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.