Skip to main content
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.

Set my Control Plane context to organization "my-org" and GVC "my-gvc".
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.

Create a new GVC called "production" with locations in aws-us-east-1 and aws-eu-west-1.

Create a GVC named "multi-cloud-app" with locations:
- azure-centralus
- gcp-me-west1
- aws-eu-central-1

Create a GVC called "staging" with these settings:
- Description: "Staging environment for QA testing"
- Locations: Frankfurt, Dublin
- Tags: environment=staging, team=platform
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

Deploy a publicly accessible workload named "web-frontend" with these specifications:
- Container image: httpd:latest
- Exposed port: 80
- Memory: 512Mi
- CPU: 500m
- Min replicas: 2
- Max replicas: 5
- Health check path: /

Create a cron workload called "data-processor" that:
- Uses image: python:3.11-slim
- Runs every hour (0 * * * *)
- Has 1Gi memory
- CPU: 500m
- Does not need external access

​
Update a Workload

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

Update the "web-frontend" workload to use image httpd:2.4-alpine.

Add these environment variables to workload "api-server":
- DATABASE_URL: postgres://db.example.com:5432/mydb
- CACHE_ENABLED: true
- LOG_LEVEL: info

​
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

Give the workload "api-server" access to the secret "db-credentials"
as environment variables. Set up the identity, policy, and binding
automatically.

Create a Docker secret called "registry-creds" for pulling images from
a private registry at registry.example.com with username "deploy" and
password "my-token".
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".

Create a policy called "api-secrets" that grants "reveal" and "use"
permissions on the secret "//secret/db-credentials" to the identity
"//gvc/production/identity/api-identity".

​
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

Get the setup guide for creating a GCP cloud account with:
- Provider: gcp
- Project ID: my-gcp-project-123

​
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.

I need to update a workload's environment variables via the REST API.
Use api_suggest to show me the endpoint, method, and body format.

​
Workload Logs

​
Query Logs

Show me the last hour of logs for workload "api-server" in GVC "production".

Get logs for workload "api-server" that contain "error" or "panic" in the last 2 hours.

Show logs for the "_accesslog" container of workload "web-frontend" in the last 30 minutes.

Get logs for workload "data-processor" between 2024-01-15T10:00:00Z and 2024-01-15T11:00:00Z.
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 authorized orgs