1. Connect the intended project
Cursor IDE with hosted MCP
For browser sign-in, merge this entry into the project’s.cursor/mcp.json.
The workspace name below lets you target this connection even if the PyAI plugin
has a separate saved login.
- Open the project in Cursor. In Customize → MCPs, open the scope menu and select the workspace. The User filter hides project entries.
- Open pyai-workspace, enable its workspace source and select Authenticate under Local.
- On the PyAI consent page, choose your organization and project. Check the displayed project ID and environment. Select Read-only access, review the permissions shown, then select Connect to PyAI.
- In a new chat in that workspace, send this prompt before asking Cursor to do anything else.
env: test and status: active. Compare scopes with the consent preview. The original 19 November login returned three permissions: omni:read for call records, trace:read for compliance findings and amd:read for answering-machine decisions. A client requesting fewer permissions can receive a subset. If the project or permissions differ from what you approved, stop, log out of Local on this workspace entry, authenticate again and repeat whoami.
Find an existing summary. For Recap, a fresh read-only login can also include recap:lookup. Check for it in whoami, then ask Cursor to use list_recap_calls to find a completed summary or get_recap if you know its call ID. Recap must be enabled in the selected organization. Its records are shared within that organization. Earlier read-only logins keep their original permissions until you reconnect and approve the updated list. Creating a summary requires recap:create. Generation and configuration require a new approval. Before any billable action, repeat the identity check on the newly authorized connection and confirm the billing terms, effective limits and approved spend.
On 19 November 2026, Cursor IDE 3.30.8 on macOS verified the selected active test project with whoami and returned the expected workflow or limitation for all nine discovery prompts. The test stopped before submission. The saved-WAV walkthrough below uses a separate local connection.
Local setup for the saved-WAV walkthrough
Use Node.js 22+ and a private CLI profile. The commands below are for macOS/Linux; the MCP JSON configuration works wherever Node andnpx are available. Keep
credentials out of prompts, source files and MCP configuration.
If you already have an authorized profile, reuse its name in every command and
configuration below. Otherwise, sign in and approve the intended organization
and project, checking the project ID and environment rather than accepting
the selected default:
env -u prevents inherited credentials or an endpoint from overriding the
selected profile. Login saves a private credential; it does not export an API
key into your shell. New sandbox creation is a separate, explicit operation in
Getting started, not a fallback after an
unexpected project or quota error.
Cursor
Merge this entry into your project’s.cursor/mcp.json, preserving other servers:
npx, use its actual absolute path from command -v npx.
Claude Code
Merge the same JSON into the project-root.mcp.json. Open Claude Code in that
project, approve the project MCP configuration when prompted, and use /mcp to
check pyai-first-result. Review shell/file permissions needed for the saved-file
steps; do not disable the client’s permission protections.
For unattended --print / --resume runs, use Claude Code 2.1.326, the
version verified to connect before the first tool call. The older 2.1.177
started a resumed turn while MCP was pending and attempted an unavailable tool.
Claude Code documents startup waiting with --mcp-config from 2.1.221;
pass the explicit config and --strict-mcp-config, and inspect connection status
before treating a missing tool as a PyAI service failure. See the
Claude Code CLI reference.
Keep test guards focused on the authorized project and submission counts. Allow
ordinary read-only CLI/file inspection; a blocked setup command is test friction,
not evidence of a failed speech or transcription request.
This setup launches local stdio. For hosted HTTP with browser OAuth, use the
MCP setup guide. A hosted connection and a local CLI
profile are separate authorizations: verify both identities before using a CLI
fallback. Hosted HTTP does not write a file onto your machine.
2. Run a read-only preflight
Ask the agent:speak:synthesize and hear:transcribe access, the intended org_id and
project_id, and the allowed spend. A ten-unit cap, credit.gated: false, or a
null key budget does not establish that a connection is free. For a zero-spend
trial, use a project whose nonbillable status has been confirmed; stop if that
cannot be established. See pricing for live usage.
Client model subscriptions or credits are separate from PyAI usage.
Choose a bound before proceeding: one synthesis, one transcription, this one
short sentence, no automatic retries, and no other audio workflows. Setting a
budget in a prompt does not create a server-side spending limit.
3. Generate and save once
After approving the preflight and filling in your own project IDs, give the agent:output_path is relative to the MCP server’s working directory. Its parent
must already exist and stay within that directory; existing files are rejected
before submission. Use the returned absolute path for subsequent commands.
The saved-file result contains output_path, bytes and status. Tool success
alone does not prove audible playback.
With hosted HTTP, download the returned audio_url/resource_link once and
record its local path. Links are bearer capabilities, expire after one hour and
are subject to connection revocation; keep them private. Local stdio without
output_path returns inline audio instead. Host player and download support
vary; see the audio result contract.
4. Play and transcribe the saved file
Open the file in a local player. On macOS, with the Mac unlocked:transcribe_audio accepts base64 audio, not a local pathname. For the saved-file
path, the tested fallback uploads the file through the CLI without passing its
base64 contents through the model:
Recover without duplicate work
What was actually tested
On November 13, 2026, both macOS clients used local MCP 0.5.11, one synthesis and one CLI transcription each, in the same verified nonbillable test project. Each downloaded a 153,644-byte WAV containing 3.2 seconds of speech. Both transcriptions matched the sentence above, and a person confirmed both recordings were clear and intelligible. PyAI credits were unchanged.
Those runs exposed unfinished WAV length fields. MCP 0.5.12 fixed the cause
by requesting complete speech output; repaired copies retained identical audio
and passed duration/playback checks. SDK/CLI 0.18.0 also shipped the saved-WAV
fix. Current setup pins are maintained from the published release manifest. The following results retain the versions actually tested.
MCP 0.5.19 setup and discovery were verified on November 17. A separate one-clip
Claude Code test saved a valid WAV in 17.9 seconds; human playback and exact
transcription passed after a client update and test-guard assistance. That was
an assisted recovery, not an uninterrupted benchmark. The historical
recordings are not a fresh audio test of those newer versions.