​
Kubiya MCP Quickstart

Connect any AI assistant to the first LLM-native automation platform in 5 minutes. Experience True Serverless Container Tools and LLM-Friendly DAG Workflows that run entirely on your infrastructure with zero dependencies.

​
⚡ Prerequisites

  • Kubiya API key (get one here)
  • No other dependencies - the Kubiya CLI is self-contained!

​
🚀 Installation

# Install Kubiya CLI (works on macOS, Linux, Windows)
curl -fsSL https://raw.githubusercontent.com/kubiyabot/cli/main/install.sh | bash

# Verify installation
kubiya --version

# Set your API key
export KUBIYA_API_KEY="kb-your-api-key-here"

​
1. Start the MCP Server

# Start the MCP server (runs in background)
kubiya mcp serve

You’ll see:

🚀 Kubiya MCP Server starting...
📡 Mode: stdio (for AI assistants)
🔑 API Key: ✅ Configured
🛠️  Tools: 21+ LLM-optimized tools available
📊 Workflows: LLM-friendly DAG engine ready
🏠 Infrastructure: Your runners detected
🛡️  Policies: Disabled (set KUBIYA_OPA_ENFORCE=true to enable)
✅ Ready for LLM connections

​
2. Configure Claude Desktop

Add this to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "kubiya": {
      "command": "kubiya",
      "args": ["mcp", "serve"],
      "env": {
        "KUBIYA_API_KEY": "kb-your-api-key-here"
      }
    }
  }
}

​
3. Restart Claude Desktop

Restart Claude Desktop and you’ll see the 🔌 MCP icon - Kubiya is connected!

​
4. Try It Out

In Claude, ask:

“Can you list the available runners and check their health status?”

“Create a tool that checks disk space and send me the results”

“Execute a kubectl command to get all pods in the cluster”

​
🎯 Method 2: Cursor IDE

​
1. Configure Cursor

Add to your Cursor settings (.cursor-settings.json):

{
  "mcp.servers": {
    "kubiya": {
      "command": "kubiya",
      "args": ["mcp", "serve"],
      "env": {
        "KUBIYA_API_KEY": "kb-your-api-key-here"
      }
    }
  }
}

​
2. Use in Cursor

Open the Composer and ask:

“Use Kubiya to deploy my application to staging”

“Check the health of our Kubernetes cluster using Kubiya tools”

​
🎯 Method 3: Custom LLM Integration

For custom applications, use the MCP protocol directly:

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import StdioServerTransport

async def use_kubiya():
    # Connect to Kubiya MCP server
    server_params = StdioServerParameters(
        command="kubiya",
        args=["mcp", "serve"],
        env={"KUBIYA_API_KEY": "kb-your-key"}
    )
    
    async with StdioServerTransport(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # Initialize connection
            await session.initialize()
            
            # List available tools
            tools = await session.list_tools()
            print(f"Available tools: {[t.name for t in tools.tools]}")
            
            # Execute a simple tool
            result = await session.call_tool(
                "execute_tool",
                {
                    "tool_name": "hello-world",
                    "args": {"content": "echo 'Hello from Kubiya!'"},
                    "runner": "auto"
                }
            )
            print(result.content)

# Run it
asyncio.run(use_kubiya())

​
🛠️ What You Can Do Now

​
1. Execute Any Tool

# In Claude/AI assistant:
"Execute a Python script that analyzes this CSV data"

# Kubiya will:
# 1. Create a Python container
# 2. Run your analysis script
# 3. Return results with live streaming

​
2. Manage Infrastructure

# In your AI:
"Check the health of our Kubernetes cluster and restart any failed pods"

# Kubiya executes:
# 1. kubectl get pods --all-namespaces --field-selector=status.phase=Failed
# 2. kubectl delete pod <failed-pods>
# 3. kubectl get pods --watch

​
3. Run Workflows

# Natural language request:
"Deploy version 2.1.0 to staging, run tests, and promote to production if successful"

# Kubiya handles the entire pipeline:
# 1. docker build -t app:2.1.0
# 2. kubectl apply -f k8s/staging/
# 3. Run integration tests  
# 4. If tests pass: kubectl apply -f k8s/production/

​
4. Data Processing

# Ask your AI:
"Process the sales data from S3, clean it, and load it into our data warehouse"

# Kubiya pipeline:
# 1. Download from S3
# 2. pandas/numpy processing
# 3. Data validation
# 4. Load to warehouse
# 5. Data quality checks

​
🚀 Advanced Configuration

​
Enable Platform APIs

For full platform management capabilities:

# Enable platform APIs (runner management, etc.)
kubiya mcp serve --allow-platform-apis

This enables additional tools:

  • create_runner - Create new runners
  • delete_runner - Remove runners
  • create_integration - Add integrations
  • create_source - Add tool sources

​
Enable Policy Enforcement

For enterprise security:

# Enable OPA policy enforcement
export KUBIYA_OPA_ENFORCE=true
kubiya mcp serve --allow-platform-apis

This adds policy validation before executing any tool or workflow.

​
Custom Configuration

Create ~/.kubiya/mcp-server.json:

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

​
🎯 Real-World Examples

​
DevOps Assistant

You: “Our application seems slow, can you investigate?”

AI + Kubiya:

  1. Checks application metrics
  2. Analyzes logs for errors
  3. Examines resource usage
  4. Identifies bottlenecks
  5. Suggests optimizations

​
Data Engineering Helper

You: “Process today’s user analytics and update the dashboard”

AI + Kubiya:

  1. Extracts data from multiple sources
  2. Runs ETL transformations
  3. Validates data quality
  4. Updates data warehouse
  5. Refreshes BI dashboards

​
Security Operations

You: “Check for any security issues in our infrastructure”

AI + Kubiya:

  1. Scans for vulnerabilities
  2. Checks access controls
  3. Reviews audit logs
  4. Validates compliance
  5. Generates security report

​
🔧 Available Tools

The Kubiya MCP server exposes 21+ powerful tools:

​
Core Execution

  • execute_tool - Run any containerized tool
  • create_on_demand_tool - Build custom tools on-the-fly
  • execute_workflow - Run complete workflows
  • execute_whitelisted_tool - Run pre-approved tools

​
Platform Management

  • list_runners - List execution infrastructure
  • check_runner_health - Monitor system health
  • find_available_runner - Auto-select optimal runners
  • list_agents - Discover AI agents
  • chat_with_agent - Multi-turn conversations

​
Tool & Source Management

  • list_sources - Browse tool repositories
  • execute_tool_from_source - Run tools from Git repos
  • discover_source - Preview tools before use
  • list_integrations - See available integrations

​
Knowledge & Security

  • search_kb - Search organizational knowledge
  • list_kb - Browse documentation
  • list_secrets - View available credentials

​
🔍 Troubleshooting

​
Common Issues

  1. MCP Connection Failed

    # Check if server is running
kubiya mcp serve --debug

# Verify API key
echo $KUBIYA_API_KEY

  2. No Tools Available

    # Make sure API key is valid
kubiya runner list  # Should show available runners

# Check configuration
cat ~/.kubiya/mcp-server.json

  3. Permission Denied

    # Check if policies are blocking execution
export KUBIYA_OPA_ENFORCE=false

# Or test permissions
kubiya policy test-tool --tool kubectl --args '{"command": "get pods"}'

​
Debug Mode

Enable detailed logging:

# Start with debug logging
kubiya --debug mcp serve

# Or via environment
export LOG_LEVEL=DEBUG
kubiya mcp serve

​
🎯 Next Steps

🔧 Tools Reference

Complete documentation of all 21+ MCP tools

🛡️ Authentication & Policies

Setup enterprise security and access control

💡 Examples & Use Cases

Real-world integration examples and patterns

🏗️ Full Stack Agents

Build complete AI applications with Kubiya

​
🆘 Getting Help

🎉 Congratulations! You’ve connected your AI assistant to the full power of Kubiya. Your AI can now execute tools, manage infrastructure, run workflows, and handle complex automation tasks with enterprise-grade security and reliability.