Tools Reference

The Kubiya MCP Server provides specialized tools organized into logical categories. Each tool supports specific operations for managing your Kubiya infrastructure.

Tool Categories

Agents

Teams

Executions

Environments

Projects

Skills

Worker Queues

Policies

Jobs

Workflows

System

Agents

Tools for managing AI agents and their configurations.

list_agents

List all agents with pagination support. Parameters:

{
  "skip": 0,        // Number of items to skip (optional)
  "limit": 10       // Maximum items to return (optional)
}

Example:

“List all my agents” “Show the first 5 agents”

get_agent

Get detailed information about a specific agent. Parameters:

{
  "id": "agent-uuid"  // Agent ID (required)
}

Example:

“Show me details about agent abc-123” “Get information for the DevOps agent”

create_agent

Create a new agent with configuration. Parameters:

{
  "name": "My Agent",                    // Agent name (required)
  "description": "Agent description",     // Description (optional)
  "instructions": "You are...",          // System prompt (required)
  "model": "gpt-4",                      // LLM model (optional)
  "project_ids": ["project-uuid"],       // Associated projects (optional)
  "environment_ids": ["env-uuid"],       // Associated environments (optional)
  "skill_ids": ["skill-uuid"],           // Toolsets/skills (optional)
  "runner_config": {...},                // Runner configuration (optional)
  "secrets": {...},                      // Secret values (optional)
  "env_vars": {...}                      // Environment variables (optional)
}

Example:

“Create an agent named ‘DevOps Helper’ that manages Kubernetes” “Create a new support agent with Slack integration”

update_agent

Update an existing agent’s configuration. Parameters:

{
  "id": "agent-uuid",              // Agent ID (required)
  "name": "Updated Name",          // New name (optional)
  "description": "New description",// New description (optional)
  "instructions": "Updated prompt",// New instructions (optional)
  // ... other agent fields
}

Example:

“Update the DevOps agent to use GPT-4” “Change the agent description”

delete_agent

Delete an agent by ID. Parameters:

{
  "id": "agent-uuid"  // Agent ID (required)
}

Example:

“Delete the test agent” “Remove agent abc-123”

Deleting an agent is permanent and cannot be undone.

execute_agent

Execute an agent with a prompt. Parameters:

{
  "agent_id": "agent-uuid",           // Agent ID (required)
  "prompt": "What is the status?",    // User prompt (required)
  "environment_id": "env-uuid"        // Environment context (optional)
}

Example:

“Execute the DevOps agent with prompt: check cluster health” “Run the support agent to create a ticket”

Use stream_execution_to_completion to monitor execution progress.

Teams

Tools for managing teams and collaborative workflows.

list_teams

List all teams with pagination. Parameters:

{
  "skip": 0,
  "limit": 10
}

Example:

“Show all teams” “List my teams”

get_team

Get detailed information about a team. Parameters:

{
  "id": "team-uuid"
}

Example:

“Get details for the DevOps team”

create_team

Create a new team. Parameters:

{
  "name": "My Team",                // Team name (required)
  "description": "Team description",// Description (optional)
  "runtime": "default",             // Runtime type (optional)
  "skill_ids": ["skill-uuid"],      // Toolsets (optional)
  "runner_config": {...}            // Configuration (optional)
}

Example:

“Create a team called ‘Infrastructure Team‘“

update_team

Update team configuration. Parameters:

{
  "id": "team-uuid",
  "name": "Updated Name",
  // ... other team fields
}

Example:

“Update the Infrastructure team configuration”

delete_team

Delete a team by ID. Parameters:

{
  "id": "team-uuid"
}

Example:

“Delete the test team”

execute_team

Execute a team with a prompt. Parameters:

{
  "team_id": "team-uuid",
  "prompt": "Deploy the application",
  "environment_id": "env-uuid"
}

Example:

“Execute the DevOps team to deploy to production”

Executions

Tools for monitoring and managing execution history.

list_executions

List execution history with filtering. Parameters:

{
  "skip": 0,
  "limit": 10,
  "status": "completed",           // Filter by status (optional)
  "entity_id": "agent-or-team-id"  // Filter by agent/team (optional)
}

Status values: pending, running, completed, failed Example:

“Show recent executions” “List failed executions from the DevOps agent”

get_execution

Get detailed execution information. Parameters:

{
  "execution_id": "exec-uuid"
}

Example:

“Show execution details for exec-123”

get_execution_messages

Get messages and logs from an execution. Parameters:

{
  "execution_id": "exec-uuid"
}

Example:

“Get logs from execution exec-123”

stream_execution_to_completion

Stream execution events until completion (batch processing). Parameters:

{
  "execution_id": "exec-uuid",
  "timeout_seconds": 270,                    // Max wait time (optional)
  "event_filter": ["tool_started", "done"]   // Event types to include (optional)
}

Event types:

message - Complete messages
message_chunk - Streaming chunks
tool_started - Tool execution started
tool_completed - Tool finished
status - Status changes
done - Execution completed
error - Error occurred

Example:

“Stream the execution and show me all events” “Monitor execution exec-123 until it completes”

Use this tool for collecting complete execution history. For interactive UIs, use get_execution_events instead.

get_execution_events

Poll for new execution events incrementally. Parameters:

{
  "execution_id": "exec-uuid",
  "last_event_id": "event-123",  // For pagination (optional)
  "limit": 50                    // Max events to return (optional)
}

Example:

“Get new events for execution exec-123” “Poll for updates on the running execution”

Use this tool for building interactive UIs that need incremental updates. Call repeatedly with last_event_id to get only new events.

Environments

Tools for managing deployment environments.

list_environments

List all environments. Parameters:

{
  "status_filter": "active"  // Filter by status (optional)
}

Example:

“List all environments” “Show active environments”

get_environment

Get environment details. Parameters:

{
  "id": "env-uuid"
}

Example:

“Get details for the production environment”

create_environment

Create a new environment. Parameters:

{
  "name": "production",                    // Environment name (required)
  "display_name": "Production",           // Display name (optional)
  "description": "Production environment", // Description (optional)
  "tags": ["prod", "main"]                // Tags (optional)
}

Example:

“Create a staging environment” “Create an environment named ‘qa-testing‘“

update_environment

Update environment configuration. Parameters:

{
  "id": "env-uuid",
  "display_name": "Updated Name",
  // ... other fields
}

Example:

“Update the staging environment description”

delete_environment

Delete an environment. Parameters:

{
  "id": "env-uuid"
}

Example:

“Delete the test environment”

Projects

Tools for managing projects.

list_projects

List all projects. Parameters:

{
  "skip": 0,
  "limit": 10
}

Example:

“Show all projects”

get_project

Get project details. Parameters:

{
  "id": "project-uuid"
}

Example:

“Get details for project abc-123”

create_project

Create a new project. Parameters:

{
  "name": "My Project",           // Project name (required)
  "key": "MYPROJ",                // Project key (required)
  "description": "Description",    // Description (optional)
  "visibility": "private"          // Visibility (optional)
}

Example:

“Create a project called ‘Infrastructure Automation‘“

update_project

Update project configuration. Parameters:

{
  "id": "project-uuid",
  "name": "Updated Name",
  // ... other fields
}

Example:

“Update project INFRA description”

delete_project

Delete a project. Parameters:

{
  "id": "project-uuid"
}

Example:

“Delete the test project”

Skills

Tools for managing skills (toolsets).

list_skills

List all available skills. Parameters:

{
  "skip": 0,
  "limit": 10
}

Example:

“Show all available skills” “List toolsets”

get_skill

Get skill details. Parameters:

{
  "id": "skill-uuid"
}

Example:

“Get details for the kubectl skill”

create_skill

Create a new skill. Parameters:

{
  "name": "File System Access",      // Skill name (required)
  "type": "file_system",             // Skill type (required)
  "description": "File operations",  // Description (optional)
  "enabled": true                    // Enabled status (optional)
}

Example:

“Create a skill for GitHub operations”

update_skill

Update skill configuration. Parameters:

{
  "id": "skill-uuid",
  "enabled": false,
  // ... other fields
}

Example:

“Disable the deprecated skill”

delete_skill

Delete a skill. Parameters:

{
  "id": "skill-uuid"
}

Example:

“Delete the test skill”

Worker Queues

Tools for managing worker queues.

list_worker_queues

List all worker queues. Parameters:

{
  "skip": 0,
  "limit": 10
}

Example:

“Show all worker queues” “List queues”

get_worker_queue

Get worker queue details. Parameters:

{
  "id": "queue-uuid"
}

Example:

“Get details for the production queue”

create_worker_queue

Create a new worker queue. Parameters:

{
  "environment_id": "env-uuid",        // Environment (required)
  "name": "default-queue",             // Queue name (required)
  "display_name": "Default Queue",     // Display name (optional)
  "max_workers": 10,                   // Max workers (optional)
  "heartbeat_interval": 60             // Heartbeat seconds (optional)
}

Example:

“Create a worker queue for the staging environment”

update_worker_queue

Update worker queue configuration. Parameters:

{
  "id": "queue-uuid",
  "max_workers": 20,
  // ... other fields
}

Example:

“Increase max workers to 20 for the production queue”

delete_worker_queue

Delete a worker queue. Parameters:

{
  "id": "queue-uuid"
}

Example:

“Delete the test queue”

Policies

Tools for managing OPA policies.

list_policies

List all policies. Parameters:

{
  "page": 1,
  "limit": 20,
  "enabled": true  // Filter by enabled status (optional)
}

Example:

“Show all policies” “List enabled policies”

get_policy

Get policy details. Parameters:

{
  "id": "policy-uuid"
}

Example:

“Get the access control policy details”

create_policy

Create a new OPA policy. Parameters:

{
  "name": "Access Control",              // Policy name (required)
  "policy_content": "package kubiya...", // OPA policy code (required)
  "description": "Controls access",      // Description (optional)
  "enabled": true,                       // Enabled status (optional)
  "tags": ["security"]                   // Tags (optional)
}

Example:

“Create a policy to restrict production access”

update_policy

Update policy configuration. Parameters:

{
  "id": "policy-uuid",
  "enabled": false,
  // ... other fields
}

Example:

“Disable the test policy”

delete_policy

Delete a policy. Parameters:

{
  "id": "policy-uuid"
}

Example:

“Delete the deprecated policy”

Jobs

Tools for managing scheduled jobs.

list_jobs

List all scheduled jobs. Parameters:

{
  "enabled": true,           // Filter by enabled status (optional)
  "trigger_type": "cron"     // Filter by trigger type (optional)
}

Trigger types: cron, webhook, manual Example:

“Show all scheduled jobs” “List enabled cron jobs”

get_job

Get job details. Parameters:

{
  "id": "job-uuid"
}

Example:

“Get details for the daily backup job”

create_job

Create a new scheduled job. Parameters:

{
  "name": "Daily Report",                        // Job name (required)
  "trigger_type": "cron",                        // Trigger type (required)
  "cron_schedule": "0 9 * * *",                  // Cron expression (for cron type)
  "cron_timezone": "America/New_York",           // Timezone (optional)
  "planning_mode": "predefined_agent",           // Planning mode (required)
  "entity_id": "agent-uuid",                     // Agent/team ID (required)
  "prompt_template": "Generate report for {{date}}" // Prompt template (required)
}

Planning modes:

predefined_agent - Use specific agent
predefined_team - Use specific team

Example:

“Create a daily job that runs the backup agent at 2 AM UTC” “Schedule a weekly report generation”

update_job

Update job configuration. Parameters:

{
  "id": "job-uuid",
  "cron_schedule": "0 10 * * *",
  // ... other fields
}

Example:

“Change the backup job schedule to 3 AM”

delete_job

Delete a job. Parameters:

{
  "id": "job-uuid"
}

Example:

“Delete the test job”

trigger_job

Manually trigger a job execution. Parameters:

{
  "id": "job-uuid",
  "variables": {           // Template variables (optional)
    "date": "2025-01-01"
  }
}

Example:

“Trigger the backup job now” “Run the report job with date=2025-12-15”

Workflows

Tools for managing workflows.

list_workflows

List all workflows. Parameters:

{
  "skip": 0,
  "limit": 10
}

Example:

“Show all workflows”

get_workflow

Get workflow details. Parameters:

{
  "workflow_id": "workflow-uuid"
}

Example:

“Get details for the deployment workflow”

create_workflow

Create a new workflow definition. Parameters:

{
  "name": "Deploy Application",
  "steps": [...],           // Workflow steps
  "description": "..."      // Description (optional)
}

Example:

“Create a workflow for deploying to Kubernetes”

System

System health and configuration tools.

health_check

Check API health status. Parameters: None Example:

“Check Kubiya API health” “Is the system healthy?”

Returns:

API status
Response time
System version

list_models

List available LLM models. Parameters: None Example:

“What models are available?” “List supported LLMs”

Returns:

Model names (e.g., gpt-4, claude-3-5-sonnet)
Model capabilities
Availability status

Tool Whitelisting

Control which tools are available using the MCP_ALLOWED_TOOLS environment variable:

# Allow all tools (default)
export MCP_ALLOWED_TOOLS="*"

# Allow specific tools
export MCP_ALLOWED_TOOLS="list_agents,get_agent,execute_agent"

# Use wildcard patterns
export MCP_ALLOWED_TOOLS="list_*,get_*"  # All list and get tools

# Read-only mode
export MCP_ALLOWED_TOOLS="list_*,get_*,health_check"

Learn more about configuration →

Next Steps

Resources

Learn about context injection

Examples

See practical usage patterns

Configuration

Configure security and environments

Quick Start

Get started with Claude Desktop

Getting Started

Reference

Guides

Documentation Index

​Tool Categories

Agents

Teams

Executions

Environments

Projects

Skills

Worker Queues

Policies

Jobs

Workflows

System

​Agents

​list_agents

​get_agent

​create_agent

​update_agent

​delete_agent

​execute_agent

​Teams

​list_teams

​get_team

​create_team

​update_team

​delete_team

​execute_team

​Executions

​list_executions

​get_execution

​get_execution_messages

​stream_execution_to_completion

​get_execution_events

​Environments

​list_environments

​get_environment

​create_environment

​update_environment

​delete_environment

​Projects

​list_projects

​get_project

​create_project

​update_project

​delete_project

​Skills

​list_skills

​get_skill

​create_skill

​update_skill

​delete_skill

​Worker Queues

​list_worker_queues

​get_worker_queue

​create_worker_queue

​update_worker_queue

​delete_worker_queue

​Policies

​list_policies

​get_policy

​create_policy

​update_policy

​delete_policy

​Jobs

​list_jobs

​get_job

​create_job

​update_job

​delete_job

​trigger_job

​Workflows

​list_workflows

​get_workflow

​create_workflow

​System

​health_check

​list_models

Tool Categories

Agents

list_agents

get_agent

create_agent

update_agent

delete_agent

execute_agent

Teams

list_teams

get_team

create_team

update_team

delete_team

execute_team

Executions

list_executions

get_execution

get_execution_messages

stream_execution_to_completion

get_execution_events

Environments

list_environments

get_environment

create_environment

update_environment

delete_environment

Projects

list_projects

get_project

create_project

update_project

delete_project

Skills

list_skills

get_skill

create_skill

update_skill

delete_skill

Worker Queues

list_worker_queues

get_worker_queue

create_worker_queue

update_worker_queue

delete_worker_queue

Policies

list_policies

get_policy

create_policy

update_policy

delete_policy

Jobs

list_jobs

get_job

create_job

update_job

delete_job

trigger_job

Workflows

list_workflows

get_workflow

create_workflow

System

health_check

list_models

Tool Whitelisting

Next Steps