# Connect AI Assistants (MCP) > Inspect and manage Watasu through MCP, with read-only access by default and optional write permissions. Connect your assistant to Watasu's hosted [Model Context Protocol](https://modelcontextprotocol.io/) server: ```text https://mcp.watasu.io/mcp ``` Your 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 ### 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 Scripted clients can send a Watasu API key: ```text Authorization: Bearer ``` 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. ## Tools 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: ```json { "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 `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`](https://docs.watasu.io/sandboxes/ssh.md). ## 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 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. [View this page on the web](https://docs.watasu.io/workflows/mcp/)