Connect AI Assistants (MCP)
Connect your assistant to Watasu’s hosted Model Context Protocol server:
https://mcp.watasu.io/mcpYour assistant can inspect apps, diagnose builds, query logs and metrics, and carry out the remote operations available in the Watasu CLI. You choose whether the connection can make changes.
Connect and choose permissions
Section titled “Connect and choose permissions”OAuth (recommended)
Section titled “OAuth (recommended)”Add the endpoint as a remote MCP server in your client. The client identifies itself through a hosted client metadata document or dynamic registration, then opens the Watasu consent page.
Choose all your teams, including future teams, or only selected teams. Review the requested permissions:
| Scope | Access |
|---|---|
read | Resources and read tools. This is the default. |
read write | Read access plus mutation and command tools. Existing app and team permissions still apply. |
offline_access | Allows renewable access where supported by the client; it does not grant additional product permissions. |
Existing read connections remain read-only. To enable changes, reconnect with a client configured to request read write. Adding the plugin or updating the server does not upgrade an existing OAuth grant. You can revoke the connection in the dashboard.
The server advertises only the tools available to the connection. A write call made with read-only authorization receives a 403 scope challenge, which clients can use to request additional consent.
API key
Section titled “API key”Scripted clients can send a Watasu API key:
Authorization: Bearer <your-api-key>Use a key with read for inspection, or read and write for changes. Existing granular API scopes and team restrictions are also enforced. A full-access API key has write access; use a restricted key when you want a read-only connection.
Read access is not a promise to redact every value: config_get, add-on connection details, logs, and command output can contain secrets or application data. Use clients you trust and avoid copying sensitive results into chat transcripts or reports.
Use tools/list to discover current schemas. Tool names below are server names; clients may add their own prefix.
| Work | Tools |
|---|---|
| Account and inventory | whoami, teams_list, apps_list, apps_info |
| Apps | apps_create, apps_rename, apps_destroy, apps_join, apps_leave, apps_lock, apps_unlock |
| Team members and app access | members_list, members_add, members_set, members_remove, members_revoke_invitation; access_list, access_add, access_update, access_remove |
| Configuration and processes | config_get, config_set, config_unset, pods_list, pods_scale, pods_type |
| Private networking | apps_trust_get, apps_trust_set |
| Domains | domains_list, domains_add, domains_refresh, domains_remove |
| Managed services | addons_catalog, addons_list, addons_info, addons_create, addons_attach, addons_detach, addons_destroy, addons_update |
| Backups and recovery | addons_backups_list, addons_backups_capture, addons_backups_download, addons_restore_upload, addons_restore, addons_promote, pg_follow |
| Observability | logs_query, logs_tail, metrics_query, traces_query, traces_get |
| Database terminals | pg_psql, addon_cli, stream_read, stream_input, stream_close |
| Sandbox execution | sandboxes_list, sandboxes_info, sandboxes_create, sandboxes_connect, sandbox_exec, sandbox_command, sandbox_command_kill, sandboxes_destroy |
Sandbox tools require write, including their status tools, matching the sandbox API’s permission model. Every tool preserves the same role checks, team boundaries, billing checks, and product validation as the corresponding API operation.
For example, apps_rename takes:
{ "name": "my-app", "app": {"name": "my-renamed-app"}}Results contain status and data in both structured content and a JSON text block. Product errors set isError: true; malformed tool arguments use MCP protocol errors. Tool annotations describe read-only, destructive, idempotent, and external effects so clients can present appropriate controls. They do not replace authorization.
Streaming and longer operations
Section titled “Streaming and longer operations”logs_tail, pg_psql, and addon_cli return a private stream handle. Read output with stream_read, passing its next_cursor as the next cursor. Continue while active and drain remaining output pages. Use stream_input to submit terminal input and stream_close when finished. Streams expire after 15 minutes and are bound to the user and credential that created them.
For a single SQL command, pass command to pg_psql. Database sessions require write even for a SELECT, because arbitrary SQL can modify data.
Backups, add-ons, and domains use the existing status tools for polling. This is the equivalent of the CLI’s wait commands. Restore uploads and backup downloads return temporary URLs for the client to transfer bytes. The server cannot open a file on your computer.
For sandbox commands, create or connect to a sandbox, call sandbox_exec, then poll sandbox_command for output and an exit code. Supply a stable idempotency_key to sandbox creation and execution when retrying. An interactive local SSH terminal, pipes, and local files still use watasu ssh.
Resources
Section titled “Resources”The existing Markdown resources remain available:
| Resource | Content |
|---|---|
watasu://overview | Accessible teams, apps, live status, latest builds, and current issues |
watasu://whoami | Identity and team scope |
watasu://teams, watasu://teams/{team}/apps | Team and app inventory |
watasu://apps, watasu://apps/status | Apps and health |
watasu://apps/{app} | App details, current release, and latest build |
watasu://apps/{app}/builds, .../builds/{number} | Build history and details |
watasu://apps/{app}/builds/{number}/logs | Build log events |
watasu://apps/{app}/builds/{number}/raw-output | Raw build output |
watasu://apps/{app}/releases/latest | Latest release |
watasu://apps/{app}/process-types | Process formation |
watasu://apps/{app}/addons, watasu://addons/{name} | Add-on details |
Local login, logout, token, and git:remote operations belong to the client machine. Source deployment still uses Git or a connected GitHub repository. Billing administration, account security, and dashboard-only settings keep their existing supported surfaces.
Protocol and authentication
Section titled “Protocol and authentication”The server supports MCP 2026-07-28, including stateless Streamable HTTP, server/discover, JSON Schema 2020-12 tool schemas, structured results, and private cache hints. Existing clients can negotiate 2025-11-25, 2025-06-18, or 2025-03-26 and use the initialized session flow.
OAuth uses PKCE, resource-bound tokens, issuer identification, and scope challenges. Public clients can use HTTPS Client ID Metadata Documents; dynamic registration remains available. Metadata documents are fetched without redirects, with bounded time and size, and public-address validation. Private-key JWT client authentication is not advertised. Optional MCP Tasks, Apps, elicitation, and other extensions are not advertised; status and stream tools work without them.
Registration and token endpoints are rate-limited. Honor Retry-After after a 429 response. Never paste tokens into a support conversation.