> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Examples

> Practical usage patterns and workflows

This page demonstrates practical usage patterns for the Kubiya MCP Server with Claude Desktop.

## Basic Operations

### List and Explore Agents

**Scenario**: Discover what agents are available in your infrastructure.

<Steps>
  <Step title="Ask Claude to list agents">
    > "What agents do I have?"

    Claude reads the `agents://list` resource and displays all agents with their descriptions.
  </Step>

  <Step title="Get details about a specific agent">
    > "Tell me more about the DevOps agent"

    Claude calls the `get_agent` tool to fetch detailed configuration.
  </Step>

  <Step title="Check agent capabilities">
    > "What skills does the DevOps agent have?"

    Claude analyzes the agent's skill configuration from the detailed response.
  </Step>
</Steps>

**Expected Response**:

```
You have 3 agents:

1. DevOps Agent (ID: agent-abc123)
   - Purpose: Kubernetes and infrastructure management
   - Model: gpt-4
   - Skills: kubectl, helm, terraform
   - Environments: production, staging

2. Support Agent (ID: agent-def456)
   - Purpose: Customer support automation
   - Model: claude-3-5-sonnet
   - Skills: slack, jira, zendesk
   - Environments: production

3. Monitoring Agent (ID: agent-ghi789)
   - Purpose: System health and alerting
   - Model: gpt-4
   - Skills: prometheus, grafana, pagerduty
   - Environments: production, staging
```

***

### Execute an Agent

**Scenario**: Run an agent to perform a task.

<Steps>
  <Step title="Execute with a simple prompt">
    > "Run the DevOps agent to check Kubernetes cluster health"

    Claude:

    1. Reads `agents://list` to find "DevOps Agent" → ID: `agent-abc123`
    2. Calls `execute_agent` with the prompt
    3. Returns execution ID
  </Step>

  <Step title="Monitor execution progress">
    > "Show me the progress"

    Claude calls `stream_execution_to_completion` to monitor real-time updates.
  </Step>

  <Step title="View final results">
    Claude displays the execution summary and agent's response.
  </Step>
</Steps>

**Example Conversation**:

<Frame>
  <div style={{padding: '20px', backgroundColor: '#f9fafb', borderRadius: '8px'}}>
    **You**: Run the DevOps agent to check our production Kubernetes cluster health

    **Claude**: I'll execute the DevOps agent for you.

    *Execution started (ID: exec-12345)*

    **Progress updates**:

    * \[00:01] Agent started
    * \[00:03] Running: kubectl get nodes
    * \[00:05] Running: kubectl get pods --all-namespaces
    * \[00:08] Running: kubectl top nodes
    * \[00:10] Analysis complete

    **Result**:
    The production Kubernetes cluster is healthy:

    * 5 nodes: All ready
    * 127 pods: 125 running, 2 pending (scheduled)
    * Resource usage: CPU 45%, Memory 62%
    * No critical alerts

    Recommended action: The 2 pending pods are new deployments waiting for rolling update completion. No intervention needed.
  </div>
</Frame>

***

## Infrastructure Management

### Create a New Environment

**Scenario**: Set up a new deployment environment.

> "Create a new environment called 'qa-testing' for our QA team with tags 'testing' and 'automation'"

**Claude's Actions**:

1. Calls `create_environment` tool
2. Confirms creation with ID and details

**Response**:

```
Environment created successfully:
- Name: qa-testing
- ID: env-qa-abc123
- Display Name: qa-testing
- Tags: testing, automation
- Status: active
- Created: 2025-12-16 10:30:00 UTC

The environment is now ready. Would you like me to:
- Create agents for this environment?
- Set up worker queues?
- Configure projects?
```

***

### Configure an Agent for Multiple Environments

**Scenario**: Update an existing agent to work in multiple environments.

> "Update the DevOps agent to also work in the qa-testing environment"

**Claude's Actions**:

1. Reads `agents://list` to find DevOps agent ID
2. Reads `environments://list` to find qa-testing environment ID
3. Calls `update_agent` with updated environment\_ids array

**Response**:

```
Updated DevOps agent (agent-abc123):
- Name: DevOps Agent
- Environments: production, staging, qa-testing (added)
- Status: active

The agent can now be executed in the qa-testing environment.
```

***

## Monitoring and Execution Tracking

### Monitor a Long-Running Execution

**Scenario**: Execute an agent and track progress in real-time.

<Steps>
  <Step title="Start execution">
    > "Execute the Infrastructure agent to provision a new database cluster in staging"

    Claude calls `execute_agent` and receives execution ID.
  </Step>

  <Step title="Stream progress">
    Claude automatically calls `stream_execution_to_completion` to monitor.
  </Step>

  <Step title="Show real-time updates">
    Claude displays events as they occur:

    * Tool started/completed events
    * Status changes
    * Progress messages
  </Step>
</Steps>

**Example Output**:

<Frame>
  <div style={{padding: '20px', backgroundColor: '#f9fafb', borderRadius: '8px'}}>
    **Execution Started** (ID: exec-78901)

    **Real-time updates**:

    ```
    [00:00] Status: PENDING → RUNNING
    [00:02] Tool started: terraform_init
    [00:10] Tool completed: terraform_init (success)
    [00:12] Tool started: terraform_plan
    [00:45] Tool completed: terraform_plan (success)
    [00:47] Waiting for approval...
    [01:15] Approval granted
    [01:17] Tool started: terraform_apply
    [03:42] Tool completed: terraform_apply (success)
    [03:44] Status: RUNNING → COMPLETED
    ```

    **Execution Summary**:

    * Duration: 3 minutes 44 seconds
    * Tools executed: 3
    * Status: COMPLETED
    * Result: Database cluster successfully provisioned in staging environment

    **Details**:

    * RDS Instance: db-staging-001
    * Endpoint: db-staging-001.abc123.us-east-1.rds.amazonaws.com:5432
    * Status: available
  </div>
</Frame>

***

### Check Execution History

**Scenario**: Review recent agent executions.

> "Show me the last 10 executions for the DevOps agent"

**Claude's Actions**:

1. Reads `agents://list` to find DevOps agent ID
2. Calls `list_executions` with filters: `entity_id=agent-abc123, limit=10`
3. Formats results

**Response**:

```
Last 10 executions for DevOps Agent:

1. exec-99999 - COMPLETED (2 mins ago)
   Prompt: "Check cluster health"
   Duration: 12 seconds

2. exec-99998 - COMPLETED (15 mins ago)
   Prompt: "Deploy application v2.3.1"
   Duration: 3m 45s

3. exec-99997 - FAILED (1 hour ago)
   Prompt: "Scale deployment to 10 replicas"
   Error: Insufficient cluster capacity

4. exec-99996 - COMPLETED (2 hours ago)
   Prompt: "Backup databases"
   Duration: 8m 12s

... (6 more)
```

***

## Job Management

### Create a Scheduled Job

**Scenario**: Set up a daily backup job.

> "Create a daily job that runs the Backup agent at 2 AM UTC to backup all production databases"

**Claude's Actions**:

1. Reads `agents://list` to find Backup agent ID
2. Calls `create_job` with cron schedule

**Response**:

```
Scheduled job created successfully:

Job Details:
- Name: Daily Database Backup
- ID: job-backup-001
- Trigger: Cron (0 2 * * *)
- Schedule: Daily at 2:00 AM UTC
- Agent: Backup Agent (agent-backup-123)
- Prompt: "Backup all production databases"
- Status: Enabled
- Next run: 2025-12-17 02:00:00 UTC

The job will run automatically according to the schedule.
```

***

### Trigger a Job Manually

**Scenario**: Run a scheduled job immediately for testing.

> "Trigger the daily backup job now"

**Claude's Actions**:

1. Reads `jobs://list` to find the job
2. Calls `trigger_job` with job ID

**Response**:

```
Job triggered successfully:
- Job: Daily Database Backup (job-backup-001)
- Execution ID: exec-manual-001
- Status: RUNNING
- Triggered: Manually by user

Monitoring execution... I'll keep you updated on the progress.

[Shows real-time progress updates]
```

***

## Team Workflows

### Execute a Team-Based Workflow

**Scenario**: Use a team of agents for a complex task.

> "Execute the Infrastructure Team to set up a complete staging environment with database, cache, and load balancer"

**Claude's Actions**:

1. Reads `teams://list` to find Infrastructure Team
2. Calls `execute_team` with detailed prompt
3. Streams execution with multiple team member updates

**Response**:

<Frame>
  <div style={{padding: '20px', backgroundColor: '#f9fafb', borderRadius: '8px'}}>
    **Team Execution Started**

    * Team: Infrastructure Team (team-infra-001)
    * Members: 3 agents
    * Execution ID: exec-team-456

    **Progress**:

    **Agent 1 - Database Agent**

    * \[00:15] Provisioning RDS instance
    * \[02:30] Database ready: db-staging.aws.com:5432

    **Agent 2 - Cache Agent**

    * \[00:20] Creating ElastiCache cluster
    * \[01:45] Cache ready: cache-staging.aws.com:6379

    **Agent 3 - Load Balancer Agent**

    * \[00:25] Configuring Application Load Balancer
    * \[01:30] Health checks configured
    * \[02:00] Load balancer active: lb-staging.aws.com

    **Team Coordination**

    * \[02:35] All components ready
    * \[02:40] Running integration tests
    * \[03:15] Tests passed

    **Execution Complete**

    * Duration: 3 minutes 15 seconds
    * Status: COMPLETED
    * Result: Staging environment fully configured

    **Environment Details**:

    * Database: PostgreSQL 14 (db-staging.aws.com:5432)
    * Cache: Redis 7.0 (cache-staging.aws.com:6379)
    * Load Balancer: ALB (lb-staging.aws.com)
    * Health: All services healthy
  </div>
</Frame>

***

## Advanced Patterns

### Conditional Execution Based on Resource State

**Scenario**: Only execute if specific conditions are met.

> "Check if there are any pending deployments in production. If yes, show me the details and ask if I want to approve them"

**Claude's Actions**:

1. Calls `execute_agent` with DevOps agent
2. Analyzes results
3. Conditionally asks for user input

**Response**:

```
I found 2 pending deployments in production:

1. api-service v2.3.1
   - Status: Waiting for approval
   - Submitted: 2 hours ago
   - Changes: Security patches, performance improvements
   - Tests: All passed

2. frontend-app v1.5.0
   - Status: Scheduled for 14:00 UTC
   - Submitted: 1 hour ago
   - Changes: New feature: Dark mode
   - Tests: All passed

Would you like me to:
1. Approve both deployments
2. Approve only one (specify which)
3. Review more details first
4. Cancel and investigate further
```

***

### Batch Operations

**Scenario**: Perform the same operation on multiple resources.

> "Create worker queues for all environments"

**Claude's Actions**:

1. Reads `environments://list` resource
2. Loops through each environment
3. Calls `create_worker_queue` for each

**Response**:

```
Creating worker queues for all environments...

✓ production: Created queue 'prod-default-queue' (queue-prod-001)
  - Max workers: 20
  - Heartbeat: 60s

✓ staging: Created queue 'staging-default-queue' (queue-staging-001)
  - Max workers: 10
  - Heartbeat: 60s

✓ qa-testing: Created queue 'qa-default-queue' (queue-qa-001)
  - Max workers: 5
  - Heartbeat: 60s

Successfully created 3 worker queues. All queues are active and ready.
```

***

### Error Handling and Recovery

**Scenario**: Handle failures gracefully and suggest recovery steps.

> "Execute the Deployment agent to deploy v3.0.0 to production"

**If execution fails**:

<Frame>
  <div style={{padding: '20px', backgroundColor: '#fef2f2', borderRadius: '8px', borderLeft: '4px solid #ef4444'}}>
    **Execution Failed** (exec-error-789)

    **Error Details**:

    * Tool: kubectl\_apply
    * Error: ImagePullBackOff
    * Message: Failed to pull image: registry.company.com/app:v3.0.0
    * Reason: Image not found in registry

    **What happened**:
    The deployment failed because the Docker image v3.0.0 doesn't exist in the registry.

    **Suggested recovery steps**:

    1. Verify the image was built and pushed:
       ```bash theme={null}
       docker images | grep app:v3.0.0
       ```
    2. Check the registry:
       ```bash theme={null}
       docker pull registry.company.com/app:v3.0.0
       ```
    3. Build and push if missing:
       ```bash theme={null}
       docker build -t registry.company.com/app:v3.0.0 .
       docker push registry.company.com/app:v3.0.0
       ```

    Would you like me to:

    * Check the build logs?
    * List available image versions?
    * Roll back to the previous version?
  </div>
</Frame>

***

## Integration Patterns

### CI/CD Integration

**Scenario**: Integrate with CI/CD pipeline.

**GitHub Actions Example**:

```yaml theme={null}
name: Deploy with Kubiya

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy using Kubiya MCP
        run: |
          # Install MCP server
          npm install -g @kubiya/control-plane-mcp-server

          # Configure environment
          export CONTROL_PLANE_API_KEY="${{ secrets.KUBIYA_API_KEY }}"
          export MCP_PROFILE="prod"

          # Use with Claude Code or API
          # ... deployment logic
```

***

### Monitoring Dashboard

**Scenario**: Build a monitoring view using read-only access.

> "Show me a status dashboard: How many agents, active executions, and worker queue health"

**Claude's Actions**:

1. Reads multiple resources in parallel:
   * `agents://list`
   * `worker-queues://list`
2. Calls `list_executions` with status filter
3. Calls `health_check`

**Response**:

```
Kubiya Infrastructure Status Dashboard
========================================

AGENTS
- Total: 5 agents
- By type: 3 DevOps, 1 Support, 1 Monitoring
- Status: All active ✓

EXECUTIONS (Last 24h)
- Total: 247 executions
- Completed: 234 (94.7%)
- Failed: 8 (3.2%)
- Running: 5 (2.0%)

WORKER QUEUES
- production: 18/20 workers active (90%)
- staging: 7/10 workers active (70%)
- qa-testing: 3/5 workers active (60%)
- Overall health: Good ✓

SYSTEM HEALTH
- API Status: Healthy ✓
- Response Time: 45ms
- Version: v1.2.3

Last updated: 2025-12-16 15:30:00 UTC
```

***

## Best Practices from Examples

<AccordionGroup>
  <Accordion title="Use descriptive prompts" icon="message">
    **Good**: "Execute the DevOps agent to check production Kubernetes cluster health"

    **Better**: "Execute the DevOps agent to check production Kubernetes cluster health, focusing on node status, pod health, and resource usage"

    More context leads to better results.
  </Accordion>

  <Accordion title="Leverage resources for context" icon="database">
    You don't need to know IDs - Claude uses resources automatically:

    **Good**: "Execute agent agent-abc123"

    **Better**: "Execute the DevOps agent"

    Claude reads resources to find the right ID.
  </Accordion>

  <Accordion title="Monitor long-running operations" icon="clock">
    For operations that take time, Claude automatically uses streaming:

    Ask: "Deploy and monitor the progress"

    Claude will show real-time updates.
  </Accordion>

  <Accordion title="Handle errors gracefully" icon="triangle-exclamation">
    When operations fail, ask Claude for help:

    "The deployment failed. What went wrong and how do I fix it?"

    Claude can analyze error messages and suggest solutions.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Tools Reference" icon="wrench" href="/mcp/tools-reference">
    Complete reference for all tools
  </Card>

  <Card title="Resources" icon="database" href="/mcp/resources">
    Learn about context injection
  </Card>

  <Card title="Configuration" icon="gear" href="/mcp/configuration">
    Advanced configuration options
  </Card>

  <Card title="Quick Start" icon="rocket" href="/mcp/quick-start">
    Get started with Claude Desktop
  </Card>
</CardGroup>