> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pyai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PyAI MCP: connect your AI app

> Connect ChatGPT, Claude, Cursor, Codex and Devin to speech, transcription, voice agents, Trace, Recap, Dub and Cast with browser OAuth.

Give your AI app natural speech, accurate transcription, reusable voice Agent profiles, call compliance, summaries, dubbing and directed narration through one Model Context Protocol server.

**Remote URL:** `https://api.pyai.com/mcp` · **Transport:** Streamable HTTP · **Authentication:** browser OAuth with project consent.

The hosted server uses the same tool implementation as `@pyai/mcp`. See the [complete guide](https://docs.pyai.com/guides/mcp), [agent handbook](https://pyai.com/mcp-agent-guide.md) and [tool schemas](https://pyai.com/mcp-tools.json).

## Connect

### Codex

```sh theme={null}
codex mcp add pyai --url https://api.pyai.com/mcp
codex mcp login pyai
```

### Claude Code

```sh theme={null}
claude mcp add --transport http pyai https://api.pyai.com/mcp
```

Run `/mcp` in Claude Code and authenticate PyAI.

### Cursor

Merge this entry into your existing `.cursor/mcp.json` or global MCP settings, then enable PyAI and finish browser authorization:

```json theme={null}
{ "mcpServers": { "pyai": { "url": "https://api.pyai.com/mcp" } } }
```

### ChatGPT, Claude chat and Devin

Add a custom remote MCP app/connector with the URL above and choose OAuth. Sign in to PyAI, select a project, inspect permissions and select **Connect to PyAI**. Custom connectors and write tools depend on your host's plan, workspace policy and enabled features. This is a custom connection; directory listing is a separate submission and review process.

The [setup page](https://pyai.com/mcp) includes host-specific steps and the Cursor install button. Existing signed-in users can go straight to project consent. New users may need to complete account setup first; ten seconds is a UX target, not a measured guarantee.

## Start with a useful request

> Use PyAI to discover the voice-agent workflow. Show my connected project, then help me create an appointment-booking agent with a greeting and escalation instructions.

Call `get_started`, `whoami`, then `discover_tools` with a use case such as `TTS`, `STT`, `voice agent`, `compliance`, `summarize calls`, `translate audio` or `narration`. Tools expose typed input schemas, read/write annotations, required scopes and structured results. Seven prompt recipes and two resources are available to hosts that support them.

| Product | Typical sequence |
| - | - |
| Speak | `list_voices` → `synthesize_speech` → play/download audio |
| Hear | `transcribe_audio` for a small attachment, or `create_transcription_job` → `get_transcription_job` |
| Agents / Omni | `list_agents` → `create_agent` → `set_agent_tools` / `set_agent_knowledge` |
| Trace | `get_trace_config` → `list_trace_interactions` → `list_trace_findings` |
| Recap | `get_recap_config` → `create_recap` → `get_recap` |
| Dub | `get_dub_capabilities` → `create_dub` → `get_dub_job` → `get_dub_audio` |
| Cast | `get_cast_capabilities` → `direct_cast_script` → `render_cast` → `get_cast_render` → `get_cast_audio` |

Creating an Agent profile does not start a microphone session or place a call. Use the PyAI SDK or widget for realtime audio. Existing knowledge-base IDs and tool definitions must be obtained from the user, console or live API; do not invent them.

## Local stdio and CLI login

Requires Node.js 22+. Run browser login once, then let your MCP host launch the server:

```sh theme={null}
npx -y @pyai/mcp@latest login
# Or use your existing CLI session: pyai login
```

```json theme={null}
{
  "mcpServers": {
    "pyai": { "command": "npx", "args": ["-y", "@pyai/mcp@latest"] }
  }
}
```

Use `--profile work` in both login and server arguments to select a saved CLI profile. `PYAI_API_KEY` may be supplied through your host's secret environment store and overrides the profile. Never paste a credential into a model prompt or check it into configuration. `--no-browser` supports remote terminals.

Local `create_sandbox_key` is an explicit optional choice for an isolated sandbox. Its key is adopted privately for that server process and never returned to the model. The hosted server does not offer this tool.

For development only, `pyai-mcp --http` starts a loopback HTTP server using your local profile. It is not the multi-user OAuth service and must not be exposed publicly.

## Permissions, results and failures

Remote authorization binds one app to one project for up to 30 days. Access tokens last 15 minutes; refresh tokens rotate. Permissions can be narrowed on refresh. Reconnect to request additional scopes. Revoke connections at [Connected AI apps](https://console.pyai.com/mcp/connections). Project, membership and key revocation invalidate access. In-flight processing may already have started; revocation does not cancel submitted jobs.

Speak and completed Dub/Cast tools return audio content and/or a download link. Hosted links are bearer capabilities valid for one hour, subject to connection revocation. Only share them with intended recipients. The backing audio is stored temporarily by PyAI; expired records are removed on subsequent artifact writes. Downloads are limited to 24 MiB. Local inline audio is limited to 8 MiB; use the CLI for larger files. `transcribe_audio` accepts at most 8 MiB decoded base64; use URL jobs for larger recordings.

Generation and persistent configuration changes require user authorization and use the selected project's normal credits and limits. Tools do not automatically retry writes. Preserve job IDs and poll pending states; after an uncertain submission timeout, inspect existing jobs before deciding whether to retry.

Errors include stable `code`, HTTP `status`, `request_id` and `retry_after` when supplied by the API. `insufficient_scope` includes an MCP authentication challenge. Credit exhaustion requires funding or an authorized sandbox; it is not a retry loop. Never expose credentials in error reports.

## Updates and compatibility

The CLI ships in `@pyai/sdk`: an SDK release can update the CLI. Global installations do not silently upgrade. Run `npm install -g @pyai/sdk@latest` to upgrade explicitly, or pin a version for reproducible automation.

The MCP npm package has its own version and release workflow. `npx -y @pyai/mcp@latest` resolves the current release when launched; an already-running server needs restarting. A pinned version remains pinned. The hosted endpoint is updated by PyAI deployments without a local npm upgrade. SDK releases alone do not deploy the hosted MCP server or publish a new MCP package.

## Contributing

```sh theme={null}
npm ci
npm run gen:tools     # curated tools from ../contracts/openapi.json
npm run gen:assets    # docs and machine-readable public discovery files
npm run gen:hosted    # shared runtime bundled into the control-plane image
npm run typecheck
npm test
npm run build
```

CI checks generated tools, public assets, hosted runtime, protocol interoperability and the installed package. Add representative input/output tests when extending a product. HTTP auth and PostgreSQL transaction tests live under `control-plane/test/mcpOAuth*.test.ts`; gateway identity tests are under `gateway/cmd/extauthz/mcp_test.go`.

The registry manifest in `server.json` is prepared for publication; its presence does not assert a live registry listing. ChatGPT and Claude app-directory submissions are separate from npm and the MCP Registry.

## Speech and calling workflows

Read the [speech and calling decision tree](https://pyai.com/agents/speech-calling.md).
`discover_tools` understands calling, inbound receptionists, outbound calls,
recordings and answering-machine detection. `openapi_get` retrieves live
operation schemas with a SHA-256 digest for detecting contract changes.

Managed number and calling tools use `telephony:manage`; Omni post-call artifacts
use `omni:read`. Existing OAuth connections must approve those scopes before
using the new tools. Purchase and dialing require explicit confirmation and
idempotency keys; unconfirmed requests return `needs_human` without submission.
Calling reaches real phone destinations and is not a sandbox simulation.

Use the SDK's `pyai.omni.connect({ rate, configure })` for realtime audio. The
[Omni frame contract](https://api.pyai.com/omni-frames.json) is generated from
the existing AsyncAPI protocol source.

## Discovery and identity output

In MCP 0.5.0, use `discover_tools({"query":"voice agent"})`; `task` is an
alias. If both are present, they must match after trimming. Omit both to list
workflows. Empty or conflicting values return `invalid_arguments`.

`whoami({})` returns concise text showing environment, scopes and account
limits. Authorized organization, project and key IDs remain in structured
output; `whoami({"verbose":true})` also includes them in text. This reduces
prompt clutter, not host access to identity metadata. Credential-shaped fields
are omitted in both modes. Never paste keys or full identity dumps into reports.

## Hosted connection boundaries

The hosted OAuth MCP connection uses existing PyAI projects and owned phone numbers.
Number purchasing is not exposed through hosted MCP. The REST API and local stdio
integration retain their separate contracts. Hosted agent tool bindings accept
saved tool IDs and enabled flags, not credentials or arbitrary connection settings.
Configure those settings privately in the PyAI console. Retained bindings preserve
their saved settings, and hosted agent responses omit connection configuration.

Supply only audio and text you are authorized to process. Do not submit payment-card
data, protected health information, government identifiers, passwords, or API keys.
If an operation exceeds the project's entitlement, report the limitation without
initiating a purchase or repeatedly resubmitting the request.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.