Examples

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.

Ask Claude to list agents

“What agents do I have?”

Claude reads the agents://list resource and displays all agents with their descriptions.

Get details about a specific agent

“Tell me more about the DevOps agent”

Claude calls the get_agent tool to fetch detailed configuration.

Check agent capabilities

“What skills does the DevOps agent have?”

Claude analyzes the agent’s skill configuration from the detailed response.

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.

Execute with a simple prompt

“Run the DevOps agent to check Kubernetes cluster health”

Claude:

Reads agents://list to find “DevOps Agent” → ID: agent-abc123
Calls execute_agent with the prompt
Returns execution ID

Monitor execution progress

“Show me the progress”

Claude calls stream_execution_to_completion to monitor real-time updates.

View final results

Claude displays the execution summary and agent’s response.

Example Conversation:

You: Run the DevOps agent to check our production Kubernetes cluster healthClaude: 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.

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:

Calls create_environment tool
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:

Reads agents://list to find DevOps agent ID
Reads environments://list to find qa-testing environment ID
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.

Start execution

“Execute the Infrastructure agent to provision a new database cluster in staging”

Claude calls execute_agent and receives execution ID.

Stream progress

Claude automatically calls stream_execution_to_completion to monitor.

Show real-time updates

Claude displays events as they occur:

Tool started/completed events
Status changes
Progress messages

Example Output:

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

Check Execution History

Scenario: Review recent agent executions.

“Show me the last 10 executions for the DevOps agent”

Claude’s Actions:

Reads agents://list to find DevOps agent ID
Calls list_executions with filters: entity_id=agent-abc123, limit=10
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:

Reads agents://list to find Backup agent ID
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:

Reads jobs://list to find the job
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:

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

Response:

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

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:

Calls execute_agent with DevOps agent
Analyzes results
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:

Reads environments://list resource
Loops through each environment
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:

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:

Verify the image was built and pushed:
```
docker images | grep app:v3.0.0
```

Check the registry:

docker pull registry.company.com/app:v3.0.0

Build and push if missing:

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?

Integration Patterns

CI/CD Integration

Scenario: Integrate with CI/CD pipeline. GitHub Actions Example:

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:

Reads multiple resources in parallel:
- agents://list
- worker-queues://list
Calls list_executions with status filter
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

Use descriptive prompts

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.

Leverage resources for context

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.

Monitor long-running operations

For operations that take time, Claude automatically uses streaming:Ask: “Deploy and monitor the progress”Claude will show real-time updates.

Handle errors gracefully

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.

Next Steps

Tools Reference

Complete reference for all tools

Resources

Learn about context injection

Configuration

Advanced configuration options

Quick Start

Get started with Claude Desktop

Getting Started

Reference

Guides

Basic Operations

List and Explore Agents

Execute an Agent

Infrastructure Management

Create a New Environment

Configure an Agent for Multiple Environments

Monitoring and Execution Tracking

Monitor a Long-Running Execution

Check Execution History

Job Management

Create a Scheduled Job

Trigger a Job Manually

Team Workflows

Execute a Team-Based Workflow

Advanced Patterns

Conditional Execution Based on Resource State

Batch Operations

Error Handling and Recovery

Integration Patterns

CI/CD Integration

Monitoring Dashboard

Best Practices from Examples

Next Steps

Tools Reference

Resources

Configuration

Quick Start

Getting Started

Reference

Guides

​Basic Operations

​List and Explore Agents

​Execute an Agent

​Infrastructure Management

​Create a New Environment

​Configure an Agent for Multiple Environments

​Monitoring and Execution Tracking

​Monitor a Long-Running Execution

​Check Execution History

​Job Management

​Create a Scheduled Job

​Trigger a Job Manually

​Team Workflows

​Execute a Team-Based Workflow

​Advanced Patterns

​Conditional Execution Based on Resource State

​Batch Operations

​Error Handling and Recovery

​Integration Patterns

​CI/CD Integration

​Monitoring Dashboard

​Best Practices from Examples

​Next Steps

Tools Reference

Resources

Configuration

Quick Start

Basic Operations

List and Explore Agents

Execute an Agent

Infrastructure Management

Create a New Environment

Configure an Agent for Multiple Environments

Monitoring and Execution Tracking

Monitor a Long-Running Execution

Check Execution History

Job Management

Create a Scheduled Job

Trigger a Job Manually

Team Workflows

Execute a Team-Based Workflow

Advanced Patterns

Conditional Execution Based on Resource State

Batch Operations

Error Handling and Recovery

Integration Patterns

CI/CD Integration

Monitoring Dashboard

Best Practices from Examples

Next Steps