Usage Examples

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 assistant can build a container image straight from a GitHub or GitLab repository and push it to your org’s private registry. No Docker daemon and no CLI are involved — the build runs on Control Plane, and the assistant follows it until the image is pushed.

Build the image "my-app:v1.0.0" in org "my-org" from
https://github.com/my-org/my-app on the main branch, then deploy it.

The first build from a private repository returns a one-time authorization link instead of starting: open it, approve access for your organization, then ask the assistant to build again. Later builds run without prompting.

To build a local folder, the assistant will hand you a cpln image build --remote command to run yourself — it has no access to your filesystem. That still needs no Docker daemon, only the CLI with a profile authenticated to the target organization. See build options.

I want to build the app in ./api and deploy it to org "my-org".

Check a Build

What is the status of build "b-1a2b3c" in org "my-org"? Show me the log if it failed.

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

Wire an Existing Secret

Secret data is managed by you — in the Console, CLI, Terraform, Pulumi, or the API. The assistant verifies a secret exists and wires access to it; it never reads or writes secret values.

Do we have a secret called "db-credentials"? List the secrets in my org
and show me its type and tags.

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

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":
Get the current workload configurations from staging
Update the production workloads to match staging
Show me the differences before and after

Debugging Session

Help me debug the workload "api-server" in production:
Show me the current status and replica count
Check if there are any error events
Get the recent logs and filter for errors
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

Get Started

MCP Clients

Setting Context

GVC Operations

Create a GVC

List GVCs

Get GVC Details

Workload Operations

Create a Workload

Update a Workload

List Workloads

Get Workload Status

Delete a Workload

Image Operations

Build an Image

Check a Build

List Images

Get Image Details

Secret Management

Wire an Existing Secret

Policy & Access Control

Manage Policies

Domain Configuration

Cloud Accounts

Suggestion Tools

Plan Before Executing

Workload Logs

Query Logs

Complex Workflows

Full Application Deployment

Environment Promotion

Debugging Session

Next Steps

Tool Setup

Workload Reference

GVC Concepts

Policy Reference

​Setting Context

​GVC Operations

​Create a GVC

​List GVCs

​Get GVC Details

​Workload Operations

​Create a Workload

​Update a Workload

​List Workloads

​Get Workload Status

​Delete a Workload

​Image Operations

​Build an Image

​Check a Build

​List Images

​Get Image Details

​Secret Management

​Wire an Existing Secret

​Policy & Access Control

​Manage Policies

​Domain Configuration

​Cloud Accounts

​Suggestion Tools

​Plan Before Executing

​Workload Logs

​Query Logs

​Complex Workflows

​Full Application Deployment

​Environment Promotion

​Debugging Session

​Next Steps

Tool Setup

Workload Reference

GVC Concepts

Policy Reference

Setting Context

GVC Operations

Create a GVC

List GVCs

Get GVC Details

Workload Operations

Create a Workload

Update a Workload

List Workloads

Get Workload Status

Delete a Workload

Image Operations

Build an Image

Check a Build

List Images

Get Image Details

Secret Management

Wire an Existing Secret

Policy & Access Control

Manage Policies

Domain Configuration

Cloud Accounts

Suggestion Tools

Plan Before Executing

Workload Logs

Query Logs

Complex Workflows

Full Application Deployment

Environment Promotion

Debugging Session

Next Steps