@pyai/mcp — PyAI Model Context Protocol server

Exposes the PyAI voice API as MCP tools so AI coding agents (Cursor, Claude Code, Codex) can go from zero to a working PyAI call with no human steps — the agent can mint its own free sandbox key and then call PyAI directly instead of guessing endpoints. Zero runtime dependencies.

Tools

| Tool | Needs a key? | Maps to | |------|--------------|---------| | create_sandbox_key | No | POST /v1/sandbox/keys — 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) — no network/credits | | whoami | Yes | GET /v1/me (scopes, env, credit posture) | | list_models | Yes | GET /v1/models | | list_voices | Yes | GET /v1/voices (optional gender, region) | | synthesize_speech | Yes | POST /v1/audio/speech → writes audio to output_path | | create_transcription_job | Yes | POST /v1/transcription/jobs (async STT for an audio_url) | | get_transcription_job | Yes | GET /v1/transcription/jobs/{id} |

The contract is https://api.pyai.com/openapi.json; these tools wrap a curated subset. No key is required to start — if PYAI_API_KEY is unset, an agent calls create_sandbox_key first and the server adopts the minted key for the rest of the session. Errors (402 credit, 429 rate limit, etc.) surface as MCP tool errors with the stable code.

Install

The server runs straight from npm with npx — no clone, no build.

Cursor — one click

Click the button (Cursor decodes the install config and prompts you), or add this to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "pyai": {
      "command": "npx",
      "args": ["-y", "@pyai/mcp"]
    }
  }
}

Add "env": { "PYAI_API_KEY": "pyai_test_..." } to pin a key, or leave it out and let the agent call create_sandbox_key.

Claude Code

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

Codex / other MCP hosts

Point the host at the stdio command npx -y @pyai/mcp, optionally with PYAI_API_KEY in the environment. The transport is newline-delimited JSON-RPC 2.0 over stdio.

Config (env)

• PYAI_API_KEY — optional. A pyai_live_/pyai_test_ key. Omit it to let the agent mint a sandbox key.
• PYAI_BASE_URL — optional, defaults to https://api.pyai.com.
• PORT — optional, HTTP transport only (default 8080).

HTTP transport (experimental)

npx @pyai/mcp --http starts a minimal HTTP JSON-RPC endpoint (POST /, GET /health) — the basis for a hosted remote server at mcp.pyai.com. A per-request Authorization: Bearer <key> overrides the env key. Each HTTP request gets an isolated client, so a key minted by create_sandbox_key is returned to that caller but is not retained globally for later callers. This is not yet a full MCP Streamable HTTP server (SSE, session ids, and OAuth are deploy-time follow-ups); the supported install today is npx over stdio.

Develop

npm install        # dev-only: typescript + @types/node
npm test           # node --test (no network; fetch is injected)
npm run typecheck
npm run build      # emit dist/ (tsc rewrites .ts imports → .js)

src/rpc.ts (dispatch) is transport-pure and unit-tested; src/tools.ts holds the tool definitions + operation logic; src/client.ts is the fetch wrapper; src/http.ts is the experimental HTTP transport. Add a tool by extending TOOLS + the callTool switch.