@pyai/mcp

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, agent handbook and tool schemas.

Connect

Codex

codex mcp add pyai --url https://api.pyai.com/mcp
codex mcp login pyai

Claude Code

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:

{ "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 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:

npx -y @pyai/mcp@latest login
# Or use your existing CLI session: pyai login

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

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