# PyAI MCP

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
codex mcp add pyai --url https://api.pyai.com/mcp
codex mcp login pyai
```

### Claude Code

```sh
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
{ "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
npx -y @pyai/mcp@latest login
# Or use your existing CLI session: pyai login
```

```json
{
  "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
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.