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

# Usage Examples

> Practical examples of using the Control Plane MCP Server with AI assistants

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](/ai/mcp#compatible-tools).

## Setting Context

Before performing operations, always set your organization and GVC context:

<CodeGroup>
  ```text Natural Language theme={null}
  Use org "my-org" and gvc "my-gvc" for the following operations.
  ```

  ```text Alternative theme={null}
  Set my Control Plane context to organization "my-org" and GVC "my-gvc".
  ```
</CodeGroup>

<Tip>Setting context once at the start of a conversation helps the AI assistant understand which resources to target.</Tip>

***

## GVC Operations

### Create a GVC

Create a new [Global Virtual Cloud](/concepts/gvc) with specific locations. You can use friendly location names or technical location IDs:

<CodeGroup>
  ```text Basic GVC (Friendly Names) theme={null}
  Create a new GVC called "production" with locations in Frankfurt, Virginia, and Dublin.
  ```

  ```text Basic GVC (Technical IDs) theme={null}
  Create a new GVC called "production" with locations in aws-us-east-1 and aws-eu-west-1.
  ```

  ```text Multi-Cloud GVC theme={null}
  Create a GVC named "multi-cloud-app" with locations:
  - azure-centralus
  - gcp-me-west1
  - aws-eu-central-1
  ```

  ```text With Description theme={null}
  Create a GVC called "staging" with these settings:
  - Description: "Staging environment for QA testing"
  - Locations: Frankfurt, Dublin
  - Tags: environment=staging, team=platform
  ```
</CodeGroup>

<Tip>
  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.
</Tip>

### List GVCs

```text theme={null}
Show me all GVCs in the org "my-org".
```

### Get GVC Details

```text theme={null}
Get the details of GVC "production" including its locations and configuration.
```

***

## Workload Operations

### Create a Workload

Create a new [workload](/concepts/workload) with various configurations:

<CodeGroup>
  ```text Basic Workload theme={null}
  Create a publicly accessible workload called "api-server" with:
  - Image: nginx:latest
  - Port: 80
  - Memory: 256Mi
  - CPU: 250m
  ```

  ```text Web Application theme={null}
  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: /
  ```

  ```text Background Worker theme={null}
  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
  ```
</CodeGroup>

### Update a Workload

<CodeGroup>
  ```text Scale Up theme={null}
  Scale the workload "api-server" to a minimum of 3 replicas and maximum of 5 replicas.
  ```

  ```text Update Image theme={null}
  Update the "web-frontend" workload to use image httpd:2.4-alpine.
  ```

  ```text Add Environment Variables theme={null}
  Add these environment variables to workload "api-server":
  - DATABASE_URL: postgres://db.example.com:5432/mydb
  - CACHE_ENABLED: true
  - LOG_LEVEL: info
  ```
</CodeGroup>

### List Workloads

```text theme={null}
List all workloads in GVC "production" with their current replica counts and status.
```

### Get Workload Status

```text theme={null}
Show me the detailed status of workload "api-server" including:
- Current replicas
- Deployment status per location
- Recent events or errors
```

### Delete a Workload

```text theme={null}
Delete the workload "old-service" from GVC "staging".
```

<Warning>Deletion operations are irreversible. The AI assistant should be configured to confirm before executing destructive operations.</Warning>

***

## Image Operations

### Build an Image

<Note>
  The `cpln` CLI must be [installed](/cli-reference/installation) and [configured with a profile](/cli-reference/get-started/profiles) 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.
</Note>

Build and push a container image to the Control Plane private registry:

```text theme={null}
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

```text theme={null}
Show me all images in org "my-org" with their tags and creation dates.
```

### Get Image Details

```text theme={null}
Get the details of image "my-app" including all available tags and their digests.
```

***

## Secret Management

### Create and Wire a Secret

<CodeGroup>
  ```text Create an Opaque Secret theme={null}
  Create a secret called "db-credentials" with type "opaque" containing:
  - DB_HOST: postgres.internal.example.com
  - DB_PORT: 5432
  - DB_NAME: myapp
  ```

  ```text Grant Workload Access to a Secret theme={null}
  Give the workload "api-server" access to the secret "db-credentials"
  as environment variables. Set up the identity, policy, and binding
  automatically.
  ```

  ```text Create a Docker Secret theme={null}
  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".
  ```
</CodeGroup>

<Tip>
  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.
</Tip>

***

## Policy & Access Control

### Manage Policies

<CodeGroup>
  ```text Create a Read-Only Policy theme={null}
  Create a policy called "viewer-workloads" that grants "view" permission
  on all workloads to the group "//group/developers".
  ```

  ```text Grant Secret Access theme={null}
  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".
  ```
</CodeGroup>

***

## Domain Configuration

```text theme={null}
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

<CodeGroup>
  ```text Setup AWS Cloud Account theme={null}
  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
  ```

  ```text Setup GCP Cloud Account theme={null}
  Get the setup guide for creating a GCP cloud account with:
  - Provider: gcp
  - Project ID: my-gcp-project-123
  ```
</CodeGroup>

***

## Suggestion Tools

### Plan Before Executing

<CodeGroup>
  ```text CLI Suggestion theme={null}
  I want to deploy a workload with a custom domain. What CLI commands
  would I need? Use cpln_suggest to plan the workflow.
  ```

  ```text API Suggestion theme={null}
  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.
  ```
</CodeGroup>

***

## Workload Logs

### Query Logs

<CodeGroup>
  ```text Recent Logs theme={null}
  Show me the last hour of logs for workload "api-server" in GVC "production".
  ```

  ```text Filter for Errors theme={null}
  Get logs for workload "api-server" that contain "error" or "panic" in the last 2 hours.
  ```

  ```text Specific Container theme={null}
  Show logs for the "_accesslog" container of workload "web-frontend" in the last 30 minutes.
  ```

  ```text Time Range theme={null}
  Get logs for workload "data-processor" between 2024-01-15T10:00:00Z and 2024-01-15T11:00:00Z.
  ```
</CodeGroup>

<Tip>
  The `get_workload_logs` tool builds LogQL queries automatically from structured parameters. Use the `query` parameter for advanced LogQL syntax.
</Tip>

***

## Complex Workflows

### Full Application Deployment

```text theme={null}
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

```text theme={null}
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

```text theme={null}
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

<CardGroup cols={2}>
  <Card title="Tool Setup" icon="gear" href="/ai/mcp">
    Configure MCP for your preferred tool
  </Card>

  <Card title="Workload Reference" icon="server" href="/reference/workload/general">
    Learn more about workload configuration options
  </Card>

  <Card title="GVC Concepts" icon="cloud" href="/concepts/gvc">
    Understand Global Virtual Clouds
  </Card>

  <Card title="Policy Reference" icon="shield" href="/reference/policy">
    Configure permissions for your authorized orgs
  </Card>
</CardGroup>