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

# Use PyAI in Cursor (and other AI agents)

> One-click install the PyAI MCP server so Cursor, Claude Code, and Codex can mint a key and call PyAI (TTS, STT, voices) directly, no endpoint guessing.

PyAI ships a [Model Context Protocol](https://modelcontextprotocol.io) server,
`@pyai/mcp`, that gives AI coding agents first-class PyAI tools: they can mint a
free sandbox key and call Speak (TTS), Hear (STT), and the voice catalog directly
instead of guessing endpoints.

## Add to Cursor, one click

[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=pyai\&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBweWFpL21jcCJdfQ==)

Click the button, Cursor decodes the install config and prompts you to confirm.
That's the whole setup: no clone, no build, no key required to start (the agent
can call `create_sandbox_key` for a free `pyai_test_` key on demand).

Prefer to do it by hand? Add this to `.cursor/mcp.json` (project) or
`~/.cursor/mcp.json` (global):

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

To pin a key instead of minting a sandbox one, add
`"env": { "PYAI_API_KEY": "pyai_live_..." }`.

## Other agents

<CodeGroup>
  ```bash Claude Code theme={null}
  claude mcp add pyai -- npx -y @pyai/mcp
  # or pin a key:
  claude mcp add pyai --env PYAI_API_KEY=pyai_test_... -- npx -y @pyai/mcp
  ```

  ```bash Codex / any MCP host theme={null}
  # Point the host at the stdio command:
  npx -y @pyai/mcp
  ```
</CodeGroup>

## What the agent gets

| Tool                                                 | Needs a key? | What it does                                                          |
| ---------------------------------------------------- | ------------ | --------------------------------------------------------------------- |
| `create_sandbox_key`                                 | No           | Mint a free `pyai_test_` key (no email/card), adopted for the session |
| `get_started`                                        | No           | Curated quickstart (auth, SDK install, TTS/STT/realtime snippets)     |
| `whoami`                                             | Yes          | Introspect the key, org, env, scopes, credit posture                  |
| `list_models`, `list_voices`                         | Yes          | Catalogs                                                              |
| `synthesize_speech`                                  | Yes          | Text-to-speech to a file                                              |
| `create_transcription_job` / `get_transcription_job` | Yes          | Async speech-to-text                                                  |

The contract behind these tools is always
[`https://api.pyai.com/openapi.json`](https://api.pyai.com/openapi.json), the
agent never invents endpoints.