# MCP server tools

> Reference for the built-in tools available on the Cloud Management Platform (CMP) MCP server

---

Site [llms.txt](/llms.txt)

---

The CMP MCP server exposes a set of built-in tools covering servers, resources, groups, environments, jobs, orders, catalog operations, power schedules, and UI links.

## Listing the available tools

List the tools a CMP server currently publishes using the management command:

```bash
./manage.py mcp_inspect
```

## Safety profiles

All tools operate within the authenticated user's permission scope. Each tool is tagged with a safety profile:

- `read_only`: The tool only reads data and cannot make changes. Multiple read-only tools can be called in parallel to gather information.
- `write`: The tool can change the state of CMP and/or your cloud resources, and requires the `write` scope (see [Authentication](/docs/cmp/developer-resources/mcp/server/#authentication)).

## Identity

| Tool | Safety | Parameters | Description |
| --- | --- | --- | --- |
| `fetch_identity` | `read_only` | None | Return the authenticated user's profile: username, email, and group memberships. |

## Servers

| Tool | Safety | Parameters | Description |
| --- | --- | --- | --- |
| `fetch_server_list` | `read_only` | `hostname` (optional): exact hostname match<br><br>`hostname_contains` (optional): servers whose hostname contains this string; ignored if `hostname` is set<br><br>`hostname_startswith` (optional): servers whose hostname starts with this string; ignored if `hostname` or `hostname_contains` is set<br><br>`group_name` (optional): exact name of the group the server belongs to<br><br>`power_status` (optional): `on` for powered-on servers, `off` for powered-off servers<br><br>`owned_by_me` (optional): when `True`, return only servers owned by the requesting user<br><br>`page` (optional; defaults to `1`)<br><br>`page_size` (optional; defaults to `25`) | List all **active** servers visible to the current user. |
| `fetch_server_details` | `read_only` | `server_id` | Return full details for a specific server: IP, OS, CPU/RAM, status, and provider metadata. |
| `fetch_server_action_parameter_options` | `read_only` | `action_id`: action global ID (for example, "SVA-abc12345")<br><br>`parameter_name`: name of the parameter from the `fetch_server_actions` schema<br><br>`server_ids`: list of server global IDs the action will run on<br><br>`current_values`: dictionary of provided parameter values; required when fetching options for a parameter that depends on another | Return the available options for a specific server action parameter. |
| `fetch_server_actions` | `read_only` | `server_id` | Return the list of server actions available to the current user for a given server, along with each action's parameter schema. |
| `run_server_action` | `write` | `server_ids`: list of server global IDs (for example, "SVR-abc12345")<br><br>`action_id`: action global ID returned by `fetch_server_actions` (for example, "SVA-abc12345")<br><br>`parameters`: dictionary of parameter values keyed by the parameter name from the `fetch_server_actions` schema | Run a server action on one or more servers. |

## Groups

| Tool | Safety | Parameters | Description |
| --- | --- | --- | --- |
| `fetch_groups` | `read_only` | None | List all groups accessible to the user. |
| `fetch_group_details` | `read_only` | `group_id` | Return full details for a specific group, including members and assigned environments. |

## Environments

| Tool | Safety | Parameters | Description |
| --- | --- | --- | --- |
| `fetch_environment_list` | `read_only` | None | List all cloud environments the user can access (for example, AWS regions, Azure subscriptions, vSphere clusters). |
| `fetch_environment_details` | `read_only` | `environment_id` | Return full details for a specific environment: provider type, connection status, and available networks. |

## Resources

| Tool | Safety | Parameters | Description |
| --- | --- | --- | --- |
| `fetch_resource_types` | `read_only` | None | List all registered resource types and their global IDs. Call this first when filtering by type. |
| `fetch_resources` | `read_only` | `name` (optional): exact resource name<br><br>`name_contains` (optional): resources whose name contains this string; ignored if `name` is set<br><br>`name_startswith` (optional): resources whose name starts with this string; ignored if `name` or `name_contains` is set<br><br>`group_name` (optional): exact name of the group the resource belongs to<br><br>`owned_by_me` (optional): when `True`, returns only resources owned by the requesting user<br><br>`resource_type_name` (optional): exact name of the resource type (for example, "S3 Bucket")<br><br>`page` (optional; defaults to `1`)<br><br>`page_size` (optional; defaults to `25`) | List resources, optionally filtered by type. |
| `fetch_resource_details` | `read_only` | `resource_id` | Return full details for a specific resource. |
| `fetch_resource_actions` | `read_only` | `resource_id` | Return the list of actions for the given resource available to the current user, along with each action's parameter schema. |
| `fetch_resource_action_parameter_options` | `read_only` | `action_id`: action global ID (for example, "RSA-abc12345")<br><br>`parameter_name`: name of the parameter from the `fetch_resource_actions` schema<br><br>`resource_ids`: list of resource global IDs the action will run on<br><br>`current_values`: dictionary of provided parameter values; required when fetching options for a parameter that depends on another | Return available options for a specific resource action parameter. |
| `run_resource_action` | `write` | `resource_ids`: list of resource global IDs (for example, "RSC-abc12345")<br><br>`action_id`: action global ID returned by `fetch_resource_actions` (for example, "RSA-abc12345")<br><br>`parameters`: dictionary of parameter values keyed by the parameter name from the `fetch_resource_actions` schema | Run a resource action on one or more resources. |

## Jobs

| Tool | Safety | Parameters | Description |
| --- | --- | --- | --- |
| `fetch_running_jobs` | `read_only` | None | List all jobs in a RUNNING state for the authenticated user. Use this to monitor async operations. |
| `fetch_job` | `read_only` | `job_id`: job global ID (for example, "JOB-abc12345") | Return the current status and details for a specific job. |

## Orders

Actions that require approval create an order. Use these tools to find orders, check their status, and act on orders awaiting approval.

| Tool | Safety | Parameters | Description |
| --- | --- | --- | --- |
| `fetch_order` | `read_only` | `order_id`: order global ID (for example, "ORD-abc12345") | Return the current status and details for a specific order. Use after an action returns an order ID to check for approval status or completion. |
| `fetch_orders` | `read_only` | `status` (optional): one of `PENDING`, `ACTIVE`, `SUCCESS`, `WARNING`, `FAILURE`, `DENIED`, `CANCELED`, `HISTORICAL`, `FCTLPAUSED`<br><br>`group_name` (optional): exact name of the group the order belongs to<br><br>`owner_username` (optional): exact username of the order's owner<br><br>`owned_by_me` (optional): when `True`, return only orders the authenticated user owns<br><br>`page` (optional; defaults to `1`)<br><br>`page_size` (optional; defaults to `25`) | List orders visible to the current user, optionally filtered by status, group, or owner. Useful for finding prior orders without knowing the ID. |
| `fetch_orders_pending_my_approval` | `read_only` | `limit` (optional; defaults to `25`, capped at `50`) | List PENDING orders the current user can actually approve (an approver in one of the order's approval groups), newest first. Narrower than `fetch_orders` with `status` set to `PENDING`. |
| `approve_order` | `write` | `order_id`: order global ID | Approve a PENDING order awaiting the user's approval. Only an approver for the order's group can approve. |
| `deny_order` | `write` | `order_id`: order global ID<br><br>`reason` (optional): explanation recorded with the denial and shown to the order's owner | Deny a PENDING order awaiting the user's approval. Only an approver for the order's group can deny. |
| `cancel_order` | `write` | `order_id`: order global ID | Cancel a PENDING order. Orders that have already started running cannot be canceled through this tool. |

## Catalog

A blueprint is an orderable catalog item that deploys infrastructure or services. These tools cover the full ordering flow.

| Tool | Safety | Parameters | Description |
| --- | --- | --- | --- |
| `fetch_catalog_items` | `read_only` | `name` (optional): exact blueprint name<br><br>`name_contains` (optional): blueprints whose name contains this string; ignored if `name` is set<br><br>`resource_type_name` (optional): filter by resource type or category (for example, "Virtual Machine")<br><br>`favorited` (optional): when `True`, restrict to favorited (featured) blueprints<br><br>`tag_names` (optional): restrict to blueprints carrying any of these tag names (see `fetch_catalog_tags`)<br><br>`page` (optional; defaults to `1`)<br><br>`page_size` (optional; defaults to `100`) | List active blueprints visible to the current user, with name, description, and resource type. All filters combine as AND. |
| `fetch_catalog_tags` | `read_only` | None | List the tags (labels) available as catalog filters, as `{name, global_id}` entries. Use the returned names with `fetch_catalog_items`. |
| `fetch_orderable_groups` | `read_only` | `blueprint_id`: blueprint global ID (for example, "BP-abc12345") | Return the groups the current user can order this blueprint under. Always call this before `fetch_blueprint_schema`. |
| `fetch_blueprint_schema` | `read_only` | `blueprint_id`: blueprint global ID<br><br>`group_id`: group global ID (for example, "GRP-abc12345") | Return the full ordering schema for a (blueprint, group) pair: blueprint-level parameters, each deployment item, and per-item parameters. Each parameter includes `has_dynamic_options` and `depends_on`. |
| `fetch_orderable_environments` | `read_only` | `blueprint_id`: blueprint global ID<br><br>`group_id`: group global ID<br><br>`service_item_slug`: slug of the deployment item from `fetch_blueprint_schema` | List the environments a user can deploy a server or Terraform deployment item to. Call when `fetch_blueprint_schema` returns `requires_environment_selection: true` for that item. |
| `fetch_blueprint_item_parameters` | `read_only` | `blueprint_id`: blueprint global ID<br><br>`group_id`: group global ID<br><br>`service_item_slug`: deployment item slug<br><br>`environment_id`: environment global ID (for example, "ENV-abc12345") | Return the parameter schema for a single server or Terraform deployment item under a chosen environment. Call after `fetch_orderable_environments`. |
| `fetch_blueprint_parameter_options` | `read_only` | `blueprint_id`: blueprint global ID<br><br>`group_id`: group global ID<br><br>`parameter_name`: name of the parameter from the schema<br><br>`service_item_slug` (optional): deployment item slug; omit for blueprint-level parameters<br><br>`environment_id` (optional): environment global ID; required for server and Terraform deployment item parameters<br><br>`current_values` (optional): parameter values already provided; required when a parameter depends on another | Return the available options for a blueprint or deployment-item parameter. Call when the schema returns `has_dynamic_options=true`, or to refresh options after a controlling parameter changes. |
| `order_catalog_item` | `write` | `blueprint_id`: blueprint global ID<br><br>`group_id`: group global ID<br><br>`parameters` (optional): dictionary of blueprint-level parameter values keyed by parameter name<br><br>`deployment_items` (optional): dictionary keyed by deployment item slug (environment, OS build, applications, and per-item parameters)<br><br>`resource_name` (optional): name for the deployed resource; defaults to the blueprint name | Validate and submit an order to deploy a blueprint. **Deploys real infrastructure with real cloud spend.** Returns an `order_id` on success; pass it to `fetch_order` to track progress. |
| `list_blueprint_orders` | `read_only` | `blueprint_id`: blueprint global ID<br><br>`limit` (optional; defaults to `5`, capped at `50`) | List the current user's most recent prior orders of this blueprint, newest first, as lightweight summaries. Use to pick a past order to re-order. |
| `fetch_blueprint_order_payload` | `read_only` | `blueprint_id`: blueprint global ID<br><br>`order_id` (optional): a specific prior order to reuse; when omitted, uses the user's most recent order of this blueprint | Reconstruct an order payload from a prior order, shaped to drop directly into `order_catalog_item`. Use to re-order or duplicate a previous deployment. |

### Ordering a catalog item

1. Call `fetch_catalog_items` (optionally filtering by name, resource type, or tag) to find the blueprint and its global ID.
1. Call `fetch_orderable_groups` for that blueprint. If one group is returned, it is used; if multiple are returned, you are asked which one to use.
1. Call `fetch_blueprint_schema` for the (blueprint, group) pair to list every parameter and deployment item.
1. For each parameter where `has_dynamic_options` is true, call `fetch_blueprint_parameter_options` for the current choices. When a deployment item reports `requires_environment_selection`, call `fetch_orderable_environments`, then `fetch_blueprint_item_parameters` for the chosen environment.
1. The assembled order is echoed back to you for explicit confirmation before submission because a catalog order deploys real infrastructure and incurs real cloud spend.
1. Call `order_catalog_item` to submit. It returns an `order_id`.
1. Call `fetch_order` to track approval status and completion.

To repeat a previous deployment, use `list_blueprint_orders` to select a past order and `fetch_blueprint_order_payload` to rebuild its parameters, then confirm and submit with `order_catalog_item`.

## Power schedules

| Tool | Safety | Parameters | Description |
| --- | --- | --- | --- |
| `fetch_server_power_schedule` | `read_only` | `server_id`: server global ID (for example, "SVR-abc12345") | Return the current power schedule for a server: whether one exists, the timezone, and each on/off pair with day names and 24-hour `HH:MM` times. |
| `set_server_power_schedule` | `write` | `server_id`: server global ID<br><br>`schedules`: list of on/off blocks, each with `on_time` (for example, "09:00"), `off_time` (for example, "17:00"), and `days` (day names, or the shortcuts `weekdays`, `weekends`, `all`)<br><br>`timezone` (optional): IANA timezone name such as "America/New_York"; defaults to "UTC" | Set the power schedule for a server, replacing any existing schedule. |
| `clear_server_power_schedule` | `write` | `server_id`: server global ID | Remove all scheduled on/off times from a server so it is no longer automatically power-cycled. |
| `fetch_resource_power_schedule` | `read_only` | `resource_id`: resource global ID (for example, "RSC-abc12345") | Return the current power schedule for a resource: whether one exists, the timezone, and each on/off pair with day names and 24-hour `HH:MM` times. |
| `set_resource_power_schedule` | `write` | `resource_id`: resource global ID<br><br>`schedules`: list of on/off blocks (same shape as the server variant)<br><br>`timezone` (optional): IANA timezone name; defaults to "UTC" | Set the power schedule for a resource, replacing any existing schedule. The resource must have at least one server. |
| `clear_resource_power_schedule` | `write` | `resource_id`: resource global ID | Remove all scheduled on/off times from a resource. |

## Links

These tools return a UI link to an object's page in CMP. They require the object's primary key (PK), not the global ID string. PKs are returned alongside other fields in list and detail responses.

| Tool | Safety | Parameters | Description |
| --- | --- | --- | --- |
| `fetch_dashboard_link` | `read_only` | None | Return a link to the CMP dashboard. |
| `fetch_server_link` | `read_only` | `server_pk`: primary key of the server | Return a link to a server's detail page. |
| `fetch_job_link` | `read_only` | `job_pk`: primary key of the job | Return a link to a job's detail page. |
| `fetch_group_link` | `read_only` | `group_pk`: primary key of the group | Return a link to a group's detail page. |
| `fetch_resource_link` | `read_only` | `resource_pk`: primary key of the resource | Return a link to a resource's detail page. |
| `fetch_order_link` | `read_only` | `order_pk`: primary key of the order | Return a link to an order's detail page. |
| `fetch_blueprint_link` | `read_only` | `blueprint_pk`: primary key of the blueprint | Return a link to a blueprint's catalog detail page. |

## Related

- [Example prompts and workflows](/docs/cmp/developer-resources/mcp/server/examples/): The prompts that reach these tools, and how the agent chains them.
- [MCP custom tools](/docs/cmp/developer-resources/mcp/custom-tools/): Publishing tools of your own alongside these.
- [MCP server integration](/docs/cmp/developer-resources/mcp/server/): Connecting a client and granting the write scope.