Skip to main content
Glama

Manage environments

manage_environments
Destructive

Add, rename or delete a project's environments (staging, qa), and record, change or forget the deployment URLs that point at them. Every change is immediate; nothing is deployed or taken offline. The variables inside an environment change through manage_secrets, project fields through manage_projects. Actions (arguments besides action and project):

  • create (name; optional slug, kind): an empty environment, kind custom unless given. The slug is made from the name when omitted and never changes. Fill it with manage_secrets action copy or import.

  • rename (environment, name): the display name only; CI jobs that use the slug keep working.

  • delete (environment): permanent, with its deployment URLs, and only for an environment holding no secret or file and not synced to Vercel. A project keeps at least one environment.

  • add_url (label, url; optional environment, primary): adds a row on every call, so repeating it duplicates the URL. Without environment it belongs to the whole project; primary true demotes the previous primary.

  • update_url (url_id; any of label, url, primary true) and delete_url (url_id): url_id is the id list_project_items item deployment_urls shows. Deleting the primary URL promotes the oldest remaining one. Errors are messages: a slug in use, an archived project, an unknown url_id, an environment that is not empty. Audited. Needs projects:write, the editor role and the scope on the environment touched; delete needs the owner role.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>",
      "project": "<project>"
    },
    "name": "manage_environments"
  }
}

Input Schema

NameRequiredDescriptionDefault
urlNoadd_url: required http(s) address. update_url: the new address
kindNocreate only: development, preview, production or custom (the default). Tokens limited to some kinds reach the environment only if its kind is one of them
nameNocreate: display name. rename: the new display name, 1 to 40 characters
slugNocreate only: the slug the other tools take, lowercase letters, digits and dashes, up to 48 characters, e.g. staging. Made from the name when omitted
labelNoadd_url: required short name, e.g. Production. update_url: the new label
actionYesWhat to do
url_idNoupdate_url, delete_url: deployment URL id, from list_project_items item deployment_urls
primaryNoadd_url: make it the project's primary URL (the previous one stops being primary). update_url: pass true only, to make it primary
projectYesProject slug from list_projects, e.g. my-app, or its id (a UUID)
environmentNorename, delete: which one. add_url: the environment the URL belongs to (default: the whole project)

Output Schema

NameRequiredDescriptionDefault
idNocreate, rename: the environment id; add_url, update_url, delete_url: the deployment URL id
urlNoadd_url, update_url: the URL's address
kindNocreate, rename: the environment's kind
nameNocreate, rename: the environment's display name
noteNocreate: with restricted, how to ask for access
slugNocreate, rename: the environment's slug
labelNoadd_url, update_url, delete_url: the URL's label
deletedNodelete, delete_url: true once removed
primaryNoadd_url, update_url: whether it is the project's primary URL
projectNodelete: the project's slug
restrictedNocreate: this token's environment limits leave the new environment out
environmentNoadd_url: the environment's slug, null for the whole project; delete: the environment deleted

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "https://json-schema.org/draft/2020-12/schema",
      +  "additionalProperties": {},
      +  "properties": {
      +    "deleted": {
      +      "description": "delete, delete_url: true once removed",
      +      "type": "boolean"
      +    },
      +    "environment": {
      +      "description": "add_url: the environment's slug, null for the whole project; delete: the environment deleted",
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "id": {
      +      "description": "create, rename: the environment id; add_url, update_url, delete_url: the deployment URL id",
      +      "type": "string"
      +    },
      +    "kind": {
      +      "description": "create, rename: the environment's kind",
      +      "enum": [
      +        "development",
      +        "preview",
      +        "production",
      +        "custom"
      +      ],
      +      "type": "string"
      +    },
      +    "label": {
      +      "description": "add_url, update_url, delete_url: the URL's label",
      +      "type": "string"
      +    },
      +    "name": {
      +      "description": "create, rename: the environment's display name",
      +      "type": "string"
      +    },
      +    "note": {
      +      "description": "create: with restricted, how to ask for access",
      +      "type": "string"
      +    },
      +    "primary": {
      +      "description": "add_url, update_url: whether it is the project's primary URL",
      +      "type": "boolean"
      +    },
      +    "project": {
      +      "description": "delete: the project's slug",
      +      "type": "string"
      +    },
      +    "restricted": {
      +      "description": "create: this token's environment limits leave the new environment out",
      +      "type": "boolean"
      +    },
      +    "slug": {
      +      "description": "create, rename: the environment's slug",
      +      "type": "string"
      +    },
      +    "url": {
      +      "description": "add_url, update_url: the URL's address",
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
  2. Added

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations, it discloses immediacy, destructive delete semantics, URL promotion/demotion, slug immutability, empty-environment constraints, audit status, and required permissions. These materially clarify the destructive and non-idempotent behavior already flagged by annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with scope, then organized by action, followed by errors and permissions. Its length is justified by six actions and ten parameters, and each section serves a clear purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex multi-action destructive tool, it covers usage boundaries, action semantics, side effects, error cases, and permission requirements. An output schema exists, so return values do not need explanation here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, the schema already defines each parameter; the description still adds cross-action meaning such as add_url duplication, primary demotion, delete_url promotion, and slug permanence. Some per-parameter wording repeats schema descriptions, so it falls short of the highest score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with specific verbs and resource: adding, renaming, deleting a project's environments and managing deployment URLs. It also explicitly separates this from manage_secrets and manage_projects, distinguishing it from close siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It names alternatives for variables and project fields and gives action-by-action usage conditions, including delete restrictions and add_url duplication. The guidance is specific enough that an agent knows which action and sibling to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources