# Generate, play and transcribe audio in Cursor or Claude Code

Get a usable speech file from your coding agent, then transcribe that same file
and compare it with the original sentence. This walkthrough follows the local
MCP → saved WAV → CLI transcription path completed in both Cursor and Claude
Code. It includes the setup and playback interventions observed in those tests.

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

```json
{
  "mcpServers": {
    "pyai-workspace": { "url": "https://api.pyai.com/mcp?auth=required" }
  }
}
```

1. Open the project in Cursor. In **Customize → MCPs**, open the scope menu and select the workspace. The **User** filter hides project entries.
2. Open **pyai-workspace**, enable its workspace source and select **Authenticate** under **Local**.
3. 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**.
4. In a new chat in that workspace, send this prompt before asking Cursor to do anything else.

```text
Use only pyai-workspace. Call whoami with verbose: true.
Show org_id, project_id, env, status, scopes, billing context and effective limits. Stop there.
```

Match the IDs and environment to the project you chose. For a test project, expect `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 and `npx` 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:

```sh
env -u PYAI_API_KEY -u PYAI_BASE_URL npx --yes @pyai/sdk@0.18.1 auth login --profile pyai-first-result
```

Inspect the profile without generating audio:

```sh
env -u PYAI_API_KEY -u PYAI_BASE_URL npx --yes @pyai/sdk@0.18.1 auth status --profile pyai-first-result --json --retries 0 --timeout 15
```

`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](https://pyai.com/getting-started.md), not a fallback after an
unexpected project or quota error.

#### Cursor

Merge this entry into your project's `.cursor/mcp.json`, preserving other servers:

```json
{
  "mcpServers": {
    "pyai-first-result": {
      "command": "npx",
      "args": ["--yes", "@pyai/mcp@0.5.26", "--profile", "pyai-first-result"],
      "env": {"PYAI_API_KEY": "", "PYAI_BASE_URL": ""}
    }
  }
}
```

The empty environment overrides make the saved profile authoritative. In
Cursor's **Customize → MCP** view, enable this server and confirm it connects.
A configuration file alone does not establish that the server is enabled. If
Cursor cannot find `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](https://code.claude.com/docs/en/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](https://pyai.com/mcp.md). 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:

```text
Use only pyai-first-result. Do not generate or submit audio yet.
Call get_started, whoami with verbose:true, and discover_tools for a short speech-to-transcription
round trip. Compare the organization/project IDs with the profile I approved.
Report environment, active status, expiry, speech/transcription scopes, billing
context and effective limits. List available English voices. Confirm where
local MCP will save its output and that the CLI uses this same project.
```

Confirm `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](https://pyai.com/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:

```text
Use my verified organization <ORG_ID> and project <PROJECT_ID> on pyai-first-result.
My maximum PyAI spend is $0; proceed only with the confirmed nonbillable project.
I authorize one synthesis and one transcription, with no automatic retries.
Generate exactly: The blue lantern is ready for tomorrow.
Choose an available English voice from the catalog. Call synthesize_speech once
with response_format wav and a new output_path of first-result.wav.
Report the returned absolute path and bytes. Verify that the file is nonempty
and its WAV header gives a finite duration under 30 seconds. Play that saved
file, then transcribe the same file using the CLI procedure below. Compare the
transcript with the original, ignoring only case and punctuation. Report each
step and any failure separately. Do not place calls, open realtime sessions,
create keys or switch projects. Stop on an uncertain submission or save failure;
inspect existing evidence before proposing another synthesis.
```

Local `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](https://pyai.com/mcp.md#audio-result-contract-by-transport).

## 4. Play and transcribe the saved file

Open the file in a local player. On macOS, with the Mac unlocked:

```sh
afplay "/absolute/path/from/output_path/first-result.wav"
```

A successful player exit and a person's confirmation that the words are audible
are separate checks. If playback fails, fix the player/device issue and replay
the **same file**; do not synthesize again.

`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:

```sh
env -u PYAI_API_KEY -u PYAI_BASE_URL npx --yes @pyai/sdk@0.18.1 transcribe "/absolute/path/from/output_path/first-result.wav" --text-only --profile pyai-first-result --retries 0 --timeout 60
```

This command submits audio to PyAI's cloud. It cannot satisfy an offline,
on-device or no-upload requirement. Run it only after the usage authorization
above. Expected text: **The blue lantern is ready for tomorrow.** Report the
actual text and any difference; do not replace the observation with the expected
answer. Save the transcript alongside the WAV and retain their paths.

## Recover without duplicate work

| Observation | Next action |
| --- | --- |
| Server disabled, missing or disconnected | Enable the intended server, inspect client status and rerun the read-only identity check. |
| Wrong project, missing scope or unknown billing | Stop before usage and correct the authorization; do not switch connections automatically. |
| Shell or file permission denied | Review the exact requested permission, then resume the unfinished step using the existing file. |
| Playback fails while the Mac is locked | Unlock it and replay the existing WAV. |
| Timeout, interrupted response or save failure after synthesis may have begun | Preserve the error code/request ID, returned bytes/link and any local file. Speak has no job ID that guarantees recovery; do not automatically repeat synthesis. |
| Agent stops after saving the file | Resume with its exact path, check completed steps, and run only the authorized unfinished step. |
| An older WAV reports an implausible duration | Preserve the file. Use a current client that requests a complete WAV; header repair of an existing file does not require new synthesis. |

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

| Client | Observed interventions |
| --- | --- |
| Cursor | The workspace MCP server needed enabling. The agent stopped and required resuming. Playback initially failed with the Mac locked; replaying the same file after unlocking succeeded. |
| Claude Code | Three shell permission denials were resolved without repeating synthesis. It used the CLI transcription fallback after checking identity and voices. |

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.

## Questions about the result

**Is this a fully autonomous, timed benchmark?** A later configured-workspace
Claude Code 2.1.326 / MCP 0.5.19 run on November 17 saved a valid WAV in
10.620 seconds and completed the two-turn speech/transcription journey in
44.643 seconds, with one synthesis, one transcription, exact text and human
playback confirmation. It needed no execution intervention. This excludes cold
installation and does not supply comparable Cursor/Codex timings. Earlier
assisted and failed attempts above remain part of the evidence. For a
future authorized benchmark, record connection start, verified identity, request
start, saved file, first playback and transcription completion using one clock,
along with permissions, errors and request counts.

**Can a hosted URL prove that the file played?** No. Verify download, file
validity, player completion and audible speech separately.

**Does a test label guarantee zero spend?** No. Confirm the actual project and
billing treatment before usage, then keep request and input bounds explicit.

Host setup references: [Cursor MCP](https://cursor.com/docs/mcp) and
[Claude Code MCP](https://code.claude.com/docs/en/mcp). For a full application,
continue with the [SDK starters](https://pyai.com/sdks.md).
