---
title: "while.sh MCP tools: what your agent can do"
url: https://while.sh/en/docs/reference/mcp-tools/
updated: 2026-11-21
---

# MCP tools

Your agent acts on while through 84 MCP tools, with your permissions and never more. Sensitive actions wait for a person's approval.

## Connect the server

while's MCP server is at `https://app.while.sh/mcp`. Your agent connects to it with OAuth: on the first call, a page opens in your browser, and you authorize while.

Without an account, the trial server `https://app.while.sh/essai` offers 21 of these tools, with no sign-in, to deploy an app as a trial.

## What a tool can do

A read-only tool changes nothing. The others act with your permissions, never more, and a token can limit them to a project, to reading or to some environments. A sensitive action, like destroying a production database or making an app public, waits for a person's approval: the tool then gives the link to the request. When you authorize your agent, you choose its level: Read, Read and act, or Administer. At the Read and act level, an administration action you can do yourself, like inviting a member or creating a token, waits for your confirmation: a while page says what the action is, for whom and on what, and you confirm it in one click.

## Tool groups

At the Read and Read and act levels, your agent first gets 40 tools, which fits in editors that limit their number, like Cursor; at the Administer level, it gets them all at once. For an action that is not among them, it loads a group with `load_tools`: `alerts` (alerts, incidents, channels), `feedback_and_docs` (page notes, feedback, searching the docs), `environments_and_storage` (domains, access links, internal apps, git repository, buckets, destroying or restarting an environment), `functions` (trying the function in front of a connection) or `administer` (members, groups, roles, access, tokens, service accounts, usage, projects, the organization). The group stays with the agent from one session to the next, and you remove it in My agents. Claude Code and VS Code see its tools right away; Cursor, Claude and ChatGPT after reconnecting while.

## Deploy

### Read while's catalog

`get_catalog` only reads. It is also on the trial server.

Parameters: `format`, `language`, `block`.

### Read the project's code

`read_source` only reads. It is also on the trial server.

Parameters: `project`, `environment`, `version`, `format`, `archive`, `path`, `start`.

### Send code from a terminal

`upload_source` acts on your projects. It is also on the trial server.

Parameters: `project`, `environment`, `terminal`.

### Write project files

`write_files` acts on your projects. It is also on the trial server.

Parameters: `project`, `files` (required), `delete`, `message`.

### Link a git repository

`link_git_repo` acts on your projects.

Parameters: `project`, `forge`, `repo`, `token`, `base_url`, `unlink`.

### Plan a deployment

`plan_deploy` acts on your projects. It is also on the trial server.

Parameters: `project`, `environment`, `plan_id`, `intent`, `from_state`, `timeout_seconds`.

### Deploy an app

`deploy_app` acts on your projects. It is also on the trial server.

Parameters: `project`, `environment`, `source_archive_base64`, `release`, `redeploy`, `image`, `digest`, `intent`, `confirm_overwrite`, `wait`, `timeout_seconds`.

### Apply a plan

`apply_plan` acts on your projects.

Parameters: `plan_id` (required), `project`, `wait`, `timeout_seconds`, `discard`.

### Roll back to a previous version

`rollback_app` acts on your projects.

Parameters: `project`, `environment`, `to`, `wait`, `approval_id`.

### Read an app's status

`get_app_status` only reads. It is also on the trial server.

Parameters: `project`, `environment`, `include`, `since`, `probe`.

Extras (`include`):

- `while_yaml`: the live version's while.yaml.
- `vulnerabilities`: the live version's known vulnerabilities, and the bots or abuse seen in its traffic.
- `openings`

### Read pending approvals

`list_approvals` only reads. It is also on the trial server.

Parameters: `id`.

## Configure an environment

### Read an environment

`get_environment` only reads. It is also on the trial server.

Parameters: `view`, `project`, `environment`, `database`.

Views (`view`):

- `variables`: the names of variables and secrets, never their values.
- `domains`: domains and their DNS proof.
- `links`: access links, without their address, which stays secret.
- `backups`: a database's last 50 backups (`database`), with the id to pass to `restore_backup`.
- `queues`: queues and their state (messages, size, consumers, lag of the slowest one).

### Set variables and secrets

`set_env` acts on your projects. It is also on the trial server.

Parameters: `project`, `environment`, `values`, `secret`, `file`, `build`, `delete`, `key`, `value`, `move`.

### Create a preview

`create_preview` acts on your projects.

Parameters: `project`, `name`, `branch`, `from`, `copy_database`, `ttl_hours`, `wait`.

### Destroy an environment

`destroy_environment` acts on your projects. It is in the `environments_and_storage` group.

Parameters: `project`, `environment` (required), `reason`, `approval_id`.

### Restart a service

`restart_app` acts on your projects. It is in the `environments_and_storage` group.

Parameters: `project`, `environment`, `service` (required).

### Verify a domain

`verify_domain` acts on your projects. It is in the `environments_and_storage` group.

Parameters: `project`, `environment`, `domain` (required).

### Share an app with a link

`request_access_link` acts on your projects.

Parameters: `project`, `environment`, `name`, `days`, `dev_address`.

## Data

### Read a database with SQL

`query_database` only reads. It is also on the trial server.

Parameters: `format`, `project`, `environment`, `database`, `sql` (required), `limit`, `max_bytes`, `timeout_seconds`.

### Back up a database

`backup_database` acts on your projects.

Parameters: `project`, `environment`, `database`, `test_restore`, `wait`.

### Restore a database

`restore_backup` acts on your projects.

Parameters: `project`, `environment`, `database`, `backup_id`, `instant`, `approval_id`, `wait`, `reason`.

### Read a bucket

`read_bucket` only reads. It is in the `environments_and_storage` group.

Parameters: `project`, `environment`, `bucket` (required), `key`, `minutes`, `download_link`, `prefix`, `next`.

### Create an upload link to a bucket

`create_upload_link` acts on your projects. It is in the `environments_and_storage` group.

Parameters: `project`, `environment`, `bucket` (required), `key` (required), `minutes`.

### Change an environment's S3 key

`rotate_s3_key` acts on your projects. It is in the `environments_and_storage` group.

Parameters: `project`, `environment`, `immediate`.

## Scheduled jobs

### List the scheduled jobs

`list_tasks` only reads.

Parameters: `project`, `environment`, `task`, `limit`.

### Run a job

`run_task` acts on your projects.

Parameters: `project`, `environment`, `task` (required), `args`, `env`, `catch_up`, `wait`, `timeout_seconds`, `approval_id`.

## Observe

### Read logs

`get_logs` only reads. It is also on the trial server.

Parameters: `project`, `environment`, `build_id`, `query`, `limit`.

### Understand what is happening

`observe_app` only reads. It is also on the trial server.

Parameters: `view`, `project`, `environment`, `query`, `range`, `trace_id`, `service`, `operation`, `since_minutes`, `min_duration`, `errors`, `limit`, `since`, `fingerprint`, `until`, `families`, `version`, `window_minutes`, `database`, `question`.

Views (`view`):

- `metrics`: the traffic and errors of the last hour, or a PromQL query (`query`) over a window (`range`).
- `traces`: a service's recent traces, or one trace in detail (`trace_id`).
- `errors`: grouped errors, or one group and its stack trace (`fingerprint`).
- `history`: versions, deployment plans and events, newest first.
- `timeline`: the project's timeline, over a period (`since`, `until`) and for some event families (`families`).
- `impact`: a version's effect (`version`), before and after, with a verdict.
- `database`: the most frequent and slowest SQL queries.
- `ask`: dated facts around a question (`question`).

### Read alerts

`list_alerts` only reads. It is in the `alerts` group.

Parameters: `view`, `project`, `status_page`, `organization`.

Views (`view`):

- `rules`: the project's alert rules.
- `incidents`: open and recent incidents.
- `channels`: where the organization's alerts go.

### Set an alert rule

`set_alert_rule` acts on your projects. It is in the `alerts` group.

Parameters: `project`, `name`, `source`, `condition`, `window_minutes`, `severity`, `message`, `channels`, `environment`, `active`, `delete`, `default`, `mute`, `public_page`.

### Acknowledge an incident

`acknowledge_incident` acts on your projects. It is in the `alerts` group.

Parameters: `project`, `incident` (required), `reason`.

### Create an alert channel

`create_alert_channel` acts on your projects. It is in the `alerts` group.

Parameters: `organization`, `type` (required), `name` (required), `address`, `url`, `min_severity`.

### Delete an alert channel

`delete_alert_channel` acts on your projects. It is in the `alerts` group.

Parameters: `organization`, `channel` (required).

### Test an alert channel

`test_alert_channel` acts on your projects. It is in the `alerts` group.

Parameters: `organization`, `channel` (required).

## Connections

### Read connections

`list_connections` only reads.

Parameters: `view`, `organization`, `connection`, `since`, `until`, `refusal`.

Views (`view`):

- `detail`: one connection (`connection`), its rules and how to call it.
- `limits`: call limits.
- `bindings`: a federated connection's bindings.

### Declare a connection

`declare_connection` acts on your projects.

Parameters: `organization`, `name` (required), `model`, `domain`, `secondary_domains`, `authentication`, `rules`, `read`, `learning_days`, `rate_per_minute`, `owner`, `label`, `project`, `apps`, `direction`, `update`.

### Configure a connection

`update_connection` acts on your projects.

Parameters: `organization`, `connection`, `method`, `pattern`, `approve_each_call`, `read`, `reason`, `lock`, `caller`, `window`, `calls`, `remove_limit`.

### Request or configure a federated binding

`set_connection_binding` acts on your projects.

Parameters: `organization`, `connection` (required), `binding`, `reason`, `resume`, `approve_production_deploys`, `project`, `caller`.

### Remove a binding

`remove_connection_binding` acts on your projects. It is in the `administer` group.

Parameters: `organization`, `connection` (required), `binding` (required), `reason`.

### Try the function in front of a connection

`try_connection_function` only reads. It is in the `functions` group.

Parameters: `organization`, `connection` (required), `version`, `request` (required), `person`, `caller`, `response`.

### Call a connection's API

`call_connection` acts on your projects.

Parameters: `organization`, `connection` (required), `method`, `path`, `body`, `type`, `call`.

## Projects

### Read projects

`get_project` only reads. It is also on the trial server.

Parameters: `project`, `include`.

Extras (`include`):

- `webhooks`: the project's webhooks.

### Create a project

`create_project` acts on your projects. It is also on the trial server.

Parameters: `project` (required), `name`, `budget_eur`, `organization`.

### Change a project's settings

`update_project_settings` acts on your projects. It is in the `administer` group.

Parameters: `project`, `visible_to_organization`, `budget_eur`, `owner`, `add_webhook`, `types`, `remove_webhook`.

### Delete a project

`delete_project` acts on your projects. It is in the `administer` group.

Parameters: `project` (required), `confirm` (required), `approval_id`.

### Read the organization's activity log

`get_activity_log` only reads.

Parameters: `organization`, `tab`, `person`, `via`, `family`, `project`, `resource`, `who`, `assignment`, `since`, `until`, `limit`, `cursor`, `verify`.

## Access and permissions

### Explain access

`explain_access` only reads.

Parameters: `organization`, `project`, `scope`, `who`, `permission`, `activity`.

### Cancel an access request

`cancel_access_request` acts on your projects. It is in the `administer` group.

Parameters: `organization`, `id` (required), `reason`.

### Review the access

`review_access` only reads. It is in the `administer` group.

Parameters: `view`, `organization`, `role`, `request`, `project`, `scope`, `unused_days`.

Views (`view`):

- `review`: what needs reviewing.
- `unused`: access no longer used.
- `export`: all access, to archive.
- `roles`: roles and their permissions.
- `requests`: access requests.

### Grant a role

`grant_role` acts on your projects.

Parameters: `organization`, `who` (required), `role` (required), `scope` (required), `until`, `days`, `reason` (required).

### Revoke a role

`revoke_role` acts on your projects.

Parameters: `organization`, `assignment` (required), `reason` (required).

### Keep a reviewed access

`keep_access` acts on your projects. It is in the `administer` group.

Parameters: `organization`, `assignment` (required), `reason`.

### Define a role

`define_role` acts on your projects. It is in the `administer` group.

Parameters: `organization`, `role` (required), `name`, `description`, `permissions`, `reason`.

### Delete a role

`delete_role` acts on your projects. It is in the `administer` group.

Parameters: `organization`, `role` (required), `reason`.

### Read sign-ins through the enterprise connection

`list_sign_ins` only reads. It is in the `administer` group.

Parameters: `organization`, `project`.

### Request access

`request_access` acts on your projects.

Parameters: `organization`, `role`, `permission`, `scope`, `days`, `reason` (required), `renew`, `for`, `tool`.

## The organization

### Read organizations

`get_organization` only reads.

Parameters: `view`, `organization`, `destination`, `minutes`.

Views (`view`):

- `detail`: the organization's members, groups and approvers.
- `existing`
- `map`: the map of its projects, databases and connections.
- `rules`: its approval rules and budget.
- `branding`: its logo and color.
- `private_network`
- `private_networks`
- `private_destination`
- `private_network_log`
- `vpn_ingress`

### Read usage

`get_usage` only reads. It is in the `administer` group.

Parameters: `view`, `project`, `organization`, `period`.

Views (`view`):

- `usage`: the current month's usage.
- `statement`: a month's statement.
- `quotas`: the organization's limits.

### Invite a person

`invite_member` acts on your projects.

Parameters: `organization`, `email` (required), `role`, `project`, `reason`, `resend`.

### Change a member's role or groups

`update_member` acts on your projects. It is in the `administer` group.

Parameters: `organization`, `email` (required), `role`, `reason`, `add_groups`, `remove_groups`.

### Remove a member

`remove_member` acts on your projects. It is in the `administer` group.

Parameters: `organization`, `email` (required).

### Create a group

`create_group` acts on your projects. It is in the `administer` group.

Parameters: `organization`, `group` (required), `sso`.

### Delete a group

`delete_group` acts on your projects. It is in the `administer` group.

Parameters: `organization`, `group` (required).

### Change the organization's settings

`update_organization_settings` acts on your projects. It is in the `administer` group.

Parameters: `organization`, `retention_months`, `confirm`, `call_retention_days`, `language`, `rules`, `budget_eur`, `approvals`, `no_budget`, `add_approvers`, `subject_type`, `resource_type`, `resource`, `remove_approvers`, `group`, `sso_group`, `accent_color`, `logo`, `logo_dark`, `logo_email`, `branding_from`, `private_network`, `vpn_ingress`.

## Tokens and service accounts

### List tokens and service accounts

`list_tokens` only reads. It is in the `administer` group.

Parameters: `view`, `organization`, `account`, `scope`, `project`, `environment`.

Views (`view`):

- `tokens`: a project's or the organization's API tokens (`scope`).
- `app_sessions`: the short-lived tokens of internal apps.
- `service_accounts`: service accounts; one account and its keys with `account`.

### Create an API token

`create_token` acts on your projects.

Parameters: `scope`, `project`, `organization`, `name`, `permissions`, `environments`, `days`.

### Shorten a token's life

`update_token_expiry` acts on your projects. It is in the `administer` group.

Parameters: `id` (required), `days` (required).

### Revoke a token

`revoke_token` acts on your projects. It is in the `administer` group.

Parameters: `app_session`, `token`.

### Create a service account

`create_service_account` acts on your projects. It is in the `administer` group.

Parameters: `organization`, `name` (required), `description`, `project`, `reason` (required).

### Enable or disable a service account

`update_service_account` acts on your projects. It is in the `administer` group.

Parameters: `organization`, `account` (required), `reason` (required), `enabled` (required).

### Delete a service account

`delete_service_account` acts on your projects. It is in the `administer` group.

Parameters: `organization`, `account` (required), `reason` (required).

### Create a service account key

`create_service_account_key` acts on your projects. It is in the `administer` group.

Parameters: `organization`, `account` (required), `replace`, `name`, `until`, `days`, `overlap_hours`.

### Revoke a service account key

`revoke_service_account_key` acts on your projects. It is in the `administer` group.

Parameters: `organization`, `account` (required), `key_id` (required), `reason` (required).

### Get a one-hour git credential

`get_git_credentials` acts on your projects. It is in the `environments_and_storage` group.

Parameters: `project`.

### Open an internal app

`open_internal_app` acts on your projects. It is in the `environments_and_storage` group.

Parameters: `project`, `service`, `environment`, `address`, `read_only`, `approval_id`.

## Feedback, docs and tool groups

### Send feedback to the while team

`send_feedback` acts on your projects. It is also on the trial server.

Parameters: `kind` (required), `message` (required), `project`, `organization`, `tool`, `route`, `reference`, `service`, `usage`, `block`, `volume`, `authentication`, `documentation`.

Kinds (`kind`):

- `bug`: while gets something wrong.
- `frustration`: what bothers the person, in their words.
- `idea`: an idea.
- `other`: anything else.
- `integration`: a service to connect; `authentication` says how it authenticates.
- `block`: a building block to open, named in `block`.

### Read feedback and replies

`list_feedback` only reads. It is in the `feedback_and_docs` group. It is also on the trial server.

Parameters: `organization`.

### Acknowledge an announcement

`acknowledge_announcement` acts on your projects.

Parameters: `id` (required).

### Read page notes

`list_page_notes` only reads. It is in the `feedback_and_docs` group.

Parameters: `project`, `state`, `limit`.

### Mark a page note

`update_page_note` acts on your projects. It is in the `feedback_and_docs` group.

Parameters: `project`, `id` (required), `state` (required), `version`, `note`.

### Open page notes in production

`update_page_notes_settings` acts on your projects. It is in the `feedback_and_docs` group.

Parameters: `project`, `production_open` (required), `environment`.

### Search while's docs

`search_docs` only reads. It is in the `feedback_and_docs` group. It is also on the trial server.

Parameters: `query` (required), `lang`.

### Load a tool group

`load_tools` changes your agent's tool list.

Parameters: `group` (required).

## Other tools

### Propose a private destination

`propose_private_destination` acts on your projects. It is in the `environments_and_storage` group.

Parameters: `organization` (required), `network` (required), `destination` (required), `target` (required), `port` (required), `tls_server_name`, `reason` (required).

## Next steps

- [Connect Claude Code](/en/guides/connect-claude-code/)
- [The REST API, operation by operation](/en/docs/reference/api/)
- [How while works](/en/docs/get-started/how-while-works/)
