Using OpenClaw? Install the live PyAI skills for Hear, Speak, Recap and Calling from ClawHub. See the OpenClaw setup guide for install commands, permissions and example prompts.
https://api.pyai.com/mcp · Transport: Streamable HTTP · Authentication: browser OAuth with project consent.
Anyone can initialize the hosted connection and list tool schemas without signing in. Every tool call, including project identity and read-only lookups, requires browser OAuth with project consent. Public discovery does not execute tools, create a project or consume speech usage. Invalid or expired credentials still require reconnection.
The hosted server uses the same tool implementation as @pyai/mcp. See the complete guide, agent handbook and tool schemas.
Create your PyAI account
New to PyAI? Use the signup link for your app, then follow the connection steps below. These links identify the setup guide that brought you to PyAI; they do not install a connector or indicate marketplace approval.Connect
Codex
Claude Code
/mcp in Claude Code and authenticate PyAI.
Cursor
For a workspace connection, merge this entry into the project’s.cursor/mcp.json.
- In Cursor IDE, open Customize → MCPs and select the workspace in the scope menu. Open pyai-workspace, enable its workspace source and select Authenticate under Local.
- On the PyAI consent page, choose your organization and project and check the displayed project ID and environment. Select Read-only access, review the permissions shown, then select Connect to PyAI.
- Send this prompt in a new workspace chat. “Use only pyai-workspace. Call whoami with verbose: true. Show org_id, project_id, env, status, scopes, billing context and effective limits. Stop there.”
scopes with the consent preview. A fresh read-only grant can include recap:lookup to list and get existing summaries in the selected organization when Recap is enabled. Creating a summary requires recap:create. Reconnect an older read-only login to approve lookup. A client requesting fewer permissions can receive a subset. Another PyAI plugin can have a saved live login. If the project or permissions differ from what you approved, stop, log out of Local on the workspace entry, authenticate again and repeat whoami. Generation and configuration require a new approval. Before any billable action, repeat the identity check on the newly authorized connection and confirm the project’s billing terms, effective limits and the user’s approved spend.
For Cursor CLI, run agent mcp enable pyai-workspace, then agent mcp login pyai-workspace in that project and perform the same check. Substitute your configured server name if different. The auth=required URL starts browser OAuth during connection. The base URL allows public catalog discovery. Existing connections using the base URL can switch to the authenticated URL and sign in. Cursor quickstart
Claude chat
For transcription and existing call records, use the dedicated PyAI Transcription & Call Records connector athttps://api.pyai.com/mcp/transcription. It has a separate OAuth audience and
only the eight tools listed in that guide. It cannot generate audio or place calls.
ChatGPT 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.
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.
For a website receptionist, verify the selected project with
whoami. Draft the widget for the exact HTTPS origin with explicit daily limits for the widget and each IP. Preview the embed, origins, limits and revision. Ask the user to approve that preview before passing body.approved=true and its revision to publish_website_widget. Return the published snippet. Visitor sessions can use project credits. These limits count sessions. If the outcome of a write is uncertain, preview the current widget before taking another action. Website widget guide
Local stdio and CLI login
Requires Node.js 22+. Run browser login once, then let your MCP host launch the server:--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
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, usediscover_tools({"query":"voice agent"}); task is an
alias. If both are present, they must match after trimming. Omit both to list
workflows. An unrelated query returns empty workflows and tools with matched: false;
voice catalog requests return only list_voices. Streaming TTS selects the SDK/API
workflow, including for phone audio. Empty or conflicting values return invalid_arguments.
whoami({}) returns organization and project IDs, environment, scopes and account
limits in text and structured output. whoami({"verbose":true}) adds key ID
and other authorized identity details to 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.Verify billing before generation
Readwhoami and compare org_id and project_id with the intended project.
Check env, plan, credit.gated, credit.available_cents, key_budget_cents
and limits before any usage. A live connection may be billed. Test usage has
sandbox caps; a null key budget or monthly limit does not mean zero cost or
unlimited free usage. Balance is not a per-request budget. Do not switch
connections or mint a different project automatically after a limit error.
Audio result contract by transport
Follow the tested first-result walkthrough to save, play and transcribe one short clip in Cursor or Claude Code. It distinguishes historical audio evidence from current setup checks and includes recovery without duplicate synthesis.
Hosted download links expire after one hour and are bearer capabilities subject
to connection revocation. A host can render a player, offer a download or show
only metadata; tool completion does not prove playback or a user-device save.
Hosted
synthesize_speech advertises an outputSchema for structuredContent.
Fields are declared at the schema root for hosts that project return types from
root properties; success/error branches additionally enforce each exact shape.
The OAuth host returns audio_url, mime_type, bytes and expires_at (Unix
milliseconds), with ok: true, code: "ok", docs_url and an additive data
alias. The inline-only loopback HTTP development host omits the URL/expiry pair.
Errors use ok: false, code and error instead of audio metadata. The schema
includes this error branch so clients can validate failures without losing the
original diagnostic. Standard MCP audio and resource_link content blocks
remain outside structuredContent; the schema does not imply that playback ran.
MCP 0.5.26 requires Node >=22 for local use and pins its internal @pyai/sdk dependency to 0.5.0.
Application SDK and MCP versions are independent; do not
install matching version numbers by assumption. Read the installed package
version and MCP initialize serverInfo.version; hosted tools/list is the
current contract, while public JSON and installed plugin metadata can lag a
release. Refresh/reconnect the host after deployment if it caches schemas.
Client evidence matrix — reviewed 19 November 2026
Current installation versions describe setup, not a fresh audio qualification. The first-result walkthrough keeps the exact historical versions, failures and interventions. No audio was generated for this review.
A fresh protocol client verified hosted MCP 0.5.20 public initialize/tools/list
and authentication boundaries on 17 November. That is a transport check, not
three independent client sessions or proof of audible output. Separately, the
team reported 0/5 PyAI mentions in fresh neutral Claude Code research sessions;
that small cold-discovery baseline does not measure connected execution.