Kubiya MCP Tools Reference

Complete documentation for all 21+ MCP tools exposed by the Kubiya MCP server. Each tool provides specific capabilities for automation, infrastructure management, and AI-powered workflows.

🔧 Core Execution Tools

execute_tool

Execute any tool with live streaming output and comprehensive parameter support. Parameters:

tool_name (string, required): Name of the tool to execute
args (object, optional): Tool-specific arguments
runner (string, optional): Runner to use (auto, default, or specific runner name)
env (object, optional): Environment variables as key-value pairs
with_file (array, optional): File mappings in [{source, destination}] format
with_volume (array, optional): Volume mappings for containers
skip_policy_check (boolean, optional): Skip policy validation (default: false)

Example:

{
  "tool_name": "kubectl",
  "args": {
    "command": "get pods -A",
    "namespace": "default"
  },
  "runner": "auto",
  "env": {
    "KUBECONFIG": "/path/to/kubeconfig"
  }
}

Use Cases:

Execute Kubernetes commands with kubectl
Run data analysis scripts with Python/pandas
Deploy infrastructure with terraform/ansible
Process files with custom Docker containers

create_on_demand_tool

Create and execute tools from definitions on-the-fly. Parameters:

name (string, required): Tool name
description (string, optional): Tool description
type (string, required): Tool type (docker, python, bash, etc.)
image (string, optional): Docker image for containerized tools
content (string, required): Tool script/content
args (object, optional): Tool arguments
runner (string, optional): Runner selection
env (object, optional): Environment variables
integrations (array, optional): Integration templates to apply

Example:

{
  "name": "disk-analyzer",
  "description": "Analyze disk usage and report findings",
  "type": "docker",
  "image": "alpine:latest",
  "content": "df -h && du -sh /* 2>/dev/null | sort -hr | head -10",
  "runner": "auto",
  "integrations": ["aws/creds"]
}

Use Cases:

Create custom monitoring tools
Build one-time data analysis scripts
Prototype new automation workflows
Execute ad-hoc system administration tasks

execute_workflow

Execute complete workflows from YAML or JSON definitions. Parameters:

workflow_definition (object, required): Complete workflow definition
variables (object, optional): Workflow variables as key-value pairs
runner (string, optional): Runner for workflow execution
skip_policy_check (boolean, optional): Skip policy validation

Example:

{
  "workflow_definition": {
    "name": "deploy-app",
    "description": "Deploy application with tests",
    "steps": [
      {
        "name": "build",
        "command": "docker build -t app:{{version}} ."
      },
      {
        "name": "test",
        "command": "docker run --rm app:{{version}} npm test"
      },
      {
        "name": "deploy",
        "command": "kubectl set image deployment/app app=app:{{version}}"
      }
    ]
  },
  "variables": {
    "version": "2.1.0",
    "environment": "production"
  },
  "runner": "prod-runner"
}

Use Cases:

Multi-step deployment pipelines
Data processing workflows
Infrastructure provisioning sequences
Automated testing and validation

execute_whitelisted_tool

Execute pre-approved tools from configuration with enhanced security. Parameters:

tool_name (string, required): Name of whitelisted tool
args (object, optional): Tool arguments
runner (string, optional): Runner selection

Example:

{
  "tool_name": "safe-kubectl",
  "args": {
    "command": "get pods",
    "namespace": "monitoring"
  },
  "runner": "prod-runner"
}

Configuration Example:

{
  "whitelisted_tools": [
    {
      "name": "safe-kubectl",
      "tool_name": "kubectl",
      "description": "Read-only Kubernetes access",
      "integrations": ["k8s/readonly"]
    }
  ]
}

🏃 Platform Management Tools

list_runners

List all available execution runners with health and status information. Parameters:

health_filter (string, optional): Filter by health status (healthy, unhealthy, unknown)
include_load (boolean, optional): Include current load metrics (default: true)

Example Response:

{
  "runners": [
    {
      "name": "kubiya-hosted",
      "health": "healthy",
      "type": "cloud",
      "load": "12%",
      "region": "us-east-1"
    },
    {
      "name": "prod-runner-1",
      "health": "healthy", 
      "type": "self-hosted",
      "load": "45%",
      "location": "on-premise"
    }
  ]
}

check_runner_health

Get detailed health information for specific runners. Parameters:

runner_name (string, optional): Specific runner name (if omitted, checks all)
include_metrics (boolean, optional): Include detailed metrics (default: false)

Example:

{
  "runner_name": "prod-runner-1"
}

find_available_runner

Auto-select the best available runner based on health, load, and requirements. Parameters:

requirements (object, optional): Resource requirements
preferred_type (string, optional): Preferred runner type (cloud, self-hosted)
region_preference (string, optional): Geographic preference

Example:

{
  "requirements": {
    "cpu": "2",
    "memory": "4Gi",
    "storage": "10Gi"
  },
  "preferred_type": "self-hosted",
  "region_preference": "us-west-2"
}

list_agents

List all available AI agents with their capabilities. Parameters:

filter (string, optional): Filter agents by capability or type
include_status (boolean, optional): Include agent status (default: true)

Example Response:

{
  "agents": [
    {
      "name": "devops-assistant",
      "description": "DevOps automation and infrastructure management",
      "capabilities": ["kubernetes", "terraform", "monitoring"],
      "status": "active"
    },
    {
      "name": "data-analyst",
      "description": "Data analysis and reporting agent",
      "capabilities": ["pandas", "sql", "visualization"],
      "status": "active"
    }
  ]
}

chat_with_agent

Initiate conversational interaction with AI agents. Parameters:

agent_name (string, required): Name of the agent to chat with
message (string, required): Message to send to the agent
conversation_id (string, optional): Continue existing conversation
context (object, optional): Additional context for the conversation

Example:

{
  "agent_name": "devops-assistant",
  "message": "Please check the health of our production Kubernetes cluster",
  "context": {
    "environment": "production",
    "priority": "high"
  }
}

🛠️ Tool & Source Management

list_sources

List all available tool sources and repositories. Parameters:

source_type (string, optional): Filter by source type (git, registry, local)
include_tools (boolean, optional): Include tool count per source (default: true)

Example Response:

{
  "sources": [
    {
      "uuid": "abc-123-def",
      "name": "DevOps Tools",
      "type": "git",
      "url": "https://github.com/company/devops-tools",
      "tool_count": 45,
      "last_updated": "2024-01-15T10:30:00Z"
    }
  ]
}

execute_tool_from_source

Execute tools directly from specific sources without adding them permanently. Parameters:

source_uuid (string, required): UUID of the source
tool_name (string, required): Name of the tool in the source
args (object, optional): Tool arguments
runner (string, optional): Runner selection

Example:

{
  "source_uuid": "abc-123-def",
  "tool_name": "security-scanner",
  "args": {
    "target": "production-cluster",
    "scan_type": "comprehensive"
  },
  "runner": "security-runner"
}

discover_source

Explore and preview tools in a source before execution. Parameters:

source_url (string, required): URL or identifier of the source
preview_limit (number, optional): Maximum tools to preview (default: 50)

Example:

{
  "source_url": "https://github.com/company/new-tools",
  "preview_limit": 10
}

Example Response:

{
  "source_info": {
    "name": "Company Tools",
    "description": "Internal automation tools",
    "tool_count": 23
  },
  "tools_preview": [
    {
      "name": "backup-tool",
      "description": "Automated backup utility",
      "type": "docker"
    }
  ]
}

list_integrations

List available integration templates for connecting to external services. Parameters:

integration_type (string, optional): Filter by type (aws, k8s, database, etc.)
include_credentials (boolean, optional): Include credential requirements (default: true)

Example Response:

{
  "integrations": [
    {
      "name": "aws/creds",
      "type": "aws",
      "description": "AWS credentials and SDK access",
      "required_secrets": ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"]
    },
    {
      "name": "k8s/incluster",
      "type": "kubernetes",
      "description": "In-cluster Kubernetes access",
      "required_secrets": []
    }
  ]
}

📚 Knowledge & Security Tools

search_kb

Search the organizational knowledge base with intelligent queries. Parameters:

query (string, required): Search query or question
limit (number, optional): Maximum results to return (default: 10)
source_filter (array, optional): Filter by specific knowledge sources

Example:

{
  "query": "How to deploy to production environment safely?",
  "limit": 5,
  "source_filter": ["deployment-docs", "security-policies"]
}

Example Response:

{
  "results": [
    {
      "title": "Production Deployment Checklist",
      "content": "...",
      "source": "deployment-docs",
      "relevance_score": 0.95,
      "last_updated": "2024-01-10T14:30:00Z"
    }
  ],
  "total_results": 12,
  "search_time_ms": 245
}

list_kb

Browse and list knowledge base entries by category or source. Parameters:

category (string, optional): Filter by category
source (string, optional): Filter by knowledge source
limit (number, optional): Maximum entries to return (default: 50)

Example:

{
  "category": "deployment",
  "limit": 20
}

list_secrets

List available secrets and credentials with proper access control. Parameters:

secret_type (string, optional): Filter by secret type (api-key, certificate, password)
environment (string, optional): Filter by environment (dev, staging, prod)

Example Response:

{
  "secrets": [
    {
      "name": "aws-prod-creds",
      "type": "api-key",
      "environment": "production",
      "created": "2024-01-01T00:00:00Z",
      "expires": "2024-12-31T23:59:59Z"
    }
  ]
}

🚀 Advanced Platform Tools

create_runner (Requires —allow-platform-apis)

Create new execution runners for the platform. Parameters:

name (string, required): Runner name
type (string, required): Runner type (docker, kubernetes, vm)
configuration (object, required): Runner-specific configuration
environment (string, optional): Target environment

Example:

{
  "name": "new-prod-runner",
  "type": "kubernetes",
  "configuration": {
    "namespace": "kubiya-runners",
    "resources": {
      "cpu": "2",
      "memory": "4Gi"
    },
    "node_selector": {
      "environment": "production"
    }
  },
  "environment": "production"
}

delete_runner (Requires —allow-platform-apis)

Remove execution runners from the platform. Parameters:

runner_name (string, required): Name of runner to delete
force (boolean, optional): Force deletion even if running tasks (default: false)

Example:

{
  "runner_name": "old-staging-runner",
  "force": false
}

create_integration (Requires —allow-platform-apis)

Create new integration templates for external services. Parameters:

name (string, required): Integration name
type (string, required): Integration type
configuration (object, required): Integration configuration
secrets (array, optional): Required secret mappings

Example:

{
  "name": "azure/creds",
  "type": "azure",
  "configuration": {
    "subscription_id": "{{AZURE_SUBSCRIPTION_ID}}",
    "tenant_id": "{{AZURE_TENANT_ID}}"
  },
  "secrets": ["AZURE_CLIENT_ID", "AZURE_CLIENT_SECRET"]
}

create_source (Requires —allow-platform-apis)

Add new tool sources to the platform. Parameters:

name (string, required): Source name
url (string, required): Source URL (Git repository, registry, etc.)
type (string, required): Source type (git, registry, local)
authentication (object, optional): Authentication configuration

Example:

{
  "name": "Company Private Tools",
  "url": "https://github.com/company/private-tools",
  "type": "git",
  "authentication": {
    "type": "token",
    "secret_name": "github-token"
  }
}

🔧 Tool Usage Patterns

Basic Tool Execution

# Simple command execution
await session.call_tool("execute_tool", {
    "tool_name": "hello-world",
    "args": {"message": "Hello from Kubiya!"}
})

Infrastructure Management

# Kubernetes cluster health check
await session.call_tool("execute_tool", {
    "tool_name": "kubectl",
    "args": {"command": "get pods -A --field-selector=status.phase!=Running"},
    "runner": "prod-runner"
})

Data Processing Pipeline

# Execute data analysis workflow
await session.call_tool("execute_workflow", {
    "workflow_definition": {
        "name": "daily-analytics",
        "steps": [
            {"name": "extract", "command": "python extract_data.py"},
            {"name": "transform", "command": "python transform_data.py"},
            {"name": "load", "command": "python load_to_warehouse.py"}
        ]
    },
    "variables": {"date": "2024-01-15"}
})

Agent Conversations

# Multi-turn conversation with DevOps agent
await session.call_tool("chat_with_agent", {
    "agent_name": "devops-assistant",
    "message": "What's the current status of our production services?",
    "context": {"environment": "production"}
})

Knowledge Base Search

# Search for deployment procedures
await session.call_tool("search_kb", {
    "query": "blue-green deployment best practices",
    "limit": 5
})

🚨 Error Handling

All tools return standardized error responses:

{
  "error": {
    "type": "ValidationError",
    "message": "Tool 'kubectl' not found",
    "code": "TOOL_NOT_FOUND",
    "details": {
      "available_tools": ["docker", "python", "bash"]
    }
  }
}

Common Error Types:

ValidationError: Invalid parameters or configuration
AuthorizationError: Insufficient permissions
ExecutionError: Tool execution failed
ResourceError: Runner or resource unavailable
PolicyError: Blocked by OPA policies

🔒 Security Considerations

Policy Enforcement

All tools respect OPA policies when KUBIYA_OPA_ENFORCE=true:

# Policy validation occurs before execution
kubiya policy test-tool --tool kubectl --args '{"command": "delete pod"}' --runner prod

Runner Selection

Use appropriate runners for security:

auto: Let Kubiya choose the best available runner
kubiya-hosted: Use Kubiya’s managed infrastructure
prod-runner: Use specific self-hosted runner for production
dev-runner: Use development runner for testing

Credential Management

Integrations handle credentials securely:

{
  "tool_name": "aws-cli",
  "args": {"command": "s3 ls"},
  "integrations": ["aws/creds"]  // Injects AWS credentials securely
}

📊 Monitoring & Observability

Tool Execution Metrics

Execution time and resource usage
Success/failure rates
Runner utilization
Policy compliance

Audit Trails

Complete logging of:

Who executed what tool
When and where execution occurred
What parameters were used
Policy decisions and outcomes

Ready to build powerful AI applications? These 21+ MCP tools provide everything needed to create enterprise-grade AI assistants that can manage infrastructure, process data, and automate complex workflows with security and reliability.

Introduction

Quick Start

Core Concepts

Using Kubiya

Workflows

MCP Integration

Administration

Reference

​Kubiya MCP Tools Reference

​🔧 Core Execution Tools

​execute_tool

​create_on_demand_tool

​execute_workflow

​execute_whitelisted_tool

​🏃 Platform Management Tools

​list_runners

​check_runner_health

​find_available_runner

​list_agents

​chat_with_agent

​🛠️ Tool & Source Management

​list_sources

​execute_tool_from_source

​discover_source

​list_integrations

​📚 Knowledge & Security Tools

​search_kb

​list_kb

​list_secrets

​🚀 Advanced Platform Tools

​create_runner (Requires —allow-platform-apis)

​delete_runner (Requires —allow-platform-apis)

​create_integration (Requires —allow-platform-apis)

​create_source (Requires —allow-platform-apis)

​🔧 Tool Usage Patterns

​Basic Tool Execution

​Infrastructure Management

​Data Processing Pipeline

​Agent Conversations

​Knowledge Base Search

​🚨 Error Handling

​🔒 Security Considerations

​Policy Enforcement

​Runner Selection

​Credential Management

​📊 Monitoring & Observability

​Tool Execution Metrics

​Audit Trails

Kubiya MCP Tools Reference

🔧 Core Execution Tools

execute_tool

create_on_demand_tool

execute_workflow

execute_whitelisted_tool

🏃 Platform Management Tools

list_runners

check_runner_health

find_available_runner

list_agents

chat_with_agent

🛠️ Tool & Source Management

list_sources

execute_tool_from_source

discover_source

list_integrations

📚 Knowledge & Security Tools

search_kb

list_kb

list_secrets

🚀 Advanced Platform Tools

create_runner (Requires —allow-platform-apis)

delete_runner (Requires —allow-platform-apis)

create_integration (Requires —allow-platform-apis)

create_source (Requires —allow-platform-apis)

🔧 Tool Usage Patterns

Basic Tool Execution

Infrastructure Management

Data Processing Pipeline

Agent Conversations

Knowledge Base Search

🚨 Error Handling

🔒 Security Considerations

Policy Enforcement

Runner Selection

Credential Management

📊 Monitoring & Observability

Tool Execution Metrics

Audit Trails