list_environments
Paginated list of a project's environments in promotion order, with their addresses, branch, flags and health, narrowed by kind, component, health or search words.
Return the environments of one project in the project's order, local to production: each with its kind, the component_id it runs (null for the whole project), its addresses, the branch deployed there, the auto_deploy and protected flags, the health the last check found and whether a change freeze is in force. Read it to find where a build lives, which branch is on staging, whether production is frozen, and the environment_id a deployment or a test run will name.
Narrow with kind (local, development, qa, staging, uat, preproduction, production, custom), component_id, health (healthy, degraded, down, unknown) and search (words in the name, an address or the hosting note). A client guest's token lists the UAT and production environments only, without the admin address, the branch, the hosting note, the region, the check's address and streak, and the notes.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Annotations
It reads and never changes anything.
Arguments
project_id*stringUUID of the project whose environments to list.
kindstringoptionalNarrow to one kind.
localdevelopmentqastaginguatpreproductionproductioncustomcomponent_idstringoptionalNarrow to the environments of one component, by UUID.
healthstringoptionalNarrow to one health.
healthydegradeddownunknownsearchstringoptionalWords the name, the address or the hosting note must contain.
limitintegeroptionalEnvironments per page (1..100, default 25).
1max100pageintegeroptional1-indexed page number.
1What it returns
{ "data": [ { "id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7081", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "component_id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70", "name": "Staging", "kind": "staging", "url": "https://staging.example.test", "api_url": "https://api.staging.example.test", "admin_url": "https://staging.example.test/admin", "branch": "develop", "hosting": "Managed containers", "region": "Singapore", "auto_deploy": true, "protected": false, "health": "healthy", "health_check_url": "https://staging.example.test/up", "last_checked_at": "2026-10-27T11:25:00+00:00", "consecutive_failures": 0, "current_version": "1.4.0", "frozen_until": null, "frozen": false, "notes": "<p>Resets its database every Sunday night.</p>", "position": 2, "created_at": "2026-10-20T09:05:00+00:00", "updated_at": "2026-10-27T11:25:00+00:00" } ], "meta": { "page": 1, "limit": 25, "total": 1, "has_more": false }}How it fails
VALIDATION_FAILEDkind or health is not one of its values, or component_id is not a UUID.
RESOURCE_NOT_FOUNDunknown project_id, or a project outside the token's scope or the person's visibility.
TOKEN_MISSING_ABILITYtoken lacks environment:view-any.
How is this guide?
Last updated on