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
Claude Code
/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:
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.
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:--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.