Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt

Use this file to discover all available pages before exploring further.

This page provides practical examples of how to interact with Control Plane through AI assistants using the MCP Server. These examples work across all compatible tools.

​
Setting Context

Before performing operations, always set your organization and GVC context: 
Use org "my-org" and gvc "my-gvc" for the following operations.
Setting context once at the start of a conversation helps the AI assistant understand which resources to target.

​
GVC Operations

​
Create a GVC

Create a new Global Virtual Cloud with specific locations. You can use friendly location names or technical location IDs: 
Create a new GVC called "production" with locations in Frankfurt, Virginia, and Dublin.
You can use friendly location names (like “Frankfurt”, “Virginia”, “Dublin”) or technical location IDs (like “aws-eu-central-1”, “aws-us-east-1”). The MCP server will resolve friendly names to the appropriate location IDs.

​
List GVCs

Show me all GVCs in the org "my-org".

​
Get GVC Details

Get the details of GVC "production" including its locations and configuration.

​
Workload Operations

​
Create a Workload

Create a new workload with various configurations: 
Create a publicly accessible workload called "api-server" with:
- Image: nginx:latest
- Port: 80
- Memory: 256Mi
- CPU: 250m

​
Update a Workload

Scale the workload "api-server" to a minimum of 3 replicas and maximum of 5 replicas.

​
List Workloads

List all workloads in GVC "production" with their current replica counts and status.

​
Get Workload Status

Show me the detailed status of workload "api-server" including:
- Current replicas
- Deployment status per location
- Recent events or errors

​
Delete a Workload

Delete the workload "old-service" from GVC "staging".
Deletion operations are irreversible. The AI assistant should be configured to confirm before executing destructive operations.

​
Image Operations

​
Build an Image

The cpln CLI must be installed and configured with a profile that is authenticated to the target organization. If no Dockerfile is present, the cpln image build command will use buildpacks to automatically create an image. Control Plane images are built for the linux/amd64 platform.
Build and push a container image to the Control Plane private registry: 
Build and push an image called "my-app:v1.0.0" from the current directory 
to the Control Plane registry in org "my-org".

​
List Images

Show me all images in org "my-org" with their tags and creation dates.

​
Get Image Details

Get the details of image "my-app" including all available tags and their digests.

​
Secret Management

​
Create and Wire a Secret

Create a secret called "db-credentials" with type "opaque" containing:
- DB_HOST: postgres.internal.example.com
- DB_PORT: 5432
- DB_NAME: myapp
When granting workload access to secrets, describe the desired outcome — the MCP server will automatically create the identity, policy, and workload binding in one step.

​
Policy & Access Control

​
Manage Policies

Create a policy called "viewer-workloads" that grants "view" permission
on all workloads to the group "//group/developers".

​
Domain Configuration

Create a domain "api.example.com" with:
- DNS mode: cname
- Certificate challenge: http01
- Port 443 (http2) routing to workload "//gvc/production/workload/api-server"

​
Cloud Accounts

Get the setup guide for creating an AWS cloud account with:
- Provider: aws
- Cloud account name: my-aws-prod
- AWS account ID: 123456789012
- Role ARN: arn:aws:iam::123456789012:role/cpln-my-org

​
Suggestion Tools

​
Plan Before Executing

I want to deploy a workload with a custom domain. What CLI commands
would I need? Use cpln_suggest to plan the workflow.

​
Workload Logs

​
Query Logs

Show me the last hour of logs for workload "api-server" in GVC "production".
The get_workload_logs tool builds LogQL queries automatically from structured parameters. Use the query parameter for advanced LogQL syntax.

​
Complex Workflows

​
Full Application Deployment

Deploy a complete application stack to Control Plane:

1. Create a GVC called "my-app-prod" in Frankfurt and Virginia

2. Create a publicly accessible workload "frontend" with:
   - Image: httpd:latest
   - Port: 80
   - Memory: 512Mi
   - CPU: 500m
   - 2-5 replicas

3. Create a publicly accessible workload "backend" with:
   - Image: nginx:latest
   - Port: 8080
   - Memory: 1Gi
   - CPU: 500m
   - 2-5 replicas
   - Environment variable SERVICE_NAME=backend

​
Environment Promotion

Promote the configuration from GVC "staging" to "production":
1. Get the current workload configurations from staging
2. Update the production workloads to match staging
3. Show me the differences before and after

​
Debugging Session

Help me debug the workload "api-server" in production:
1. Show me the current status and replica count
2. Check if there are any error events
3. Get the recent logs and filter for errors
4. Show me the resource utilization

​
Next Steps

Tool Setup

Configure MCP for your preferred tool

Workload Reference

Learn more about workload configuration options

GVC Concepts

Understand Global Virtual Clouds

Policy Reference

Configure permissions for your service account