Quick Start

This guide will help you connect the Kubiya MCP Server to Claude Desktop and start using it within minutes.

Prerequisites

Before you begin, ensure you have:

Node.js 20+ installed
Kubiya API key from the dashboard
Claude Desktop installed (download here)

Step 1: Install the MCP Server

Choose your preferred installation method:

Global Install
npx (No Install)

npm install -g @kubiya/control-plane-mcp-server

Step 2: Get Your API Key

Navigate to the Kubiya Dashboard
Click on Settings in the left sidebar
Select API Keys
Click Create New API Key
Copy the generated JWT token

Store your API key securely. Don’t commit it to version control or share it publicly.

Step 3: Configure Claude Desktop

Add the Kubiya MCP Server to your Claude Desktop configuration file:

macOS
Windows
Linux

File location: ~/Library/Application Support/Claude/claude_desktop_config.json

Using npx
Using global install

{
  "mcpServers": {
    "kubiya-control-plane": {
      "command": "npx",
      "args": ["@kubiya/control-plane-mcp-server"],
      "env": {
        "CONTROL_PLANE_API_KEY": "your-jwt-token-here",
        "MCP_PROFILE": "prod"
      }
    }
  }
}

{
  "mcpServers": {
    "kubiya-control-plane": {
      "command": "kubiya-mcp",
      "args": [],
      "env": {
        "CONTROL_PLANE_API_KEY": "your-jwt-token-here",
        "MCP_PROFILE": "prod"
      }
    }
  }
}

Replace your-jwt-token-here with your actual Kubiya API key from Step 2.

File location: %APPDATA%\Claude\claude_desktop_config.json

Using npx
Using global install

{
  "mcpServers": {
    "kubiya-control-plane": {
      "command": "npx",
      "args": ["@kubiya/control-plane-mcp-server"],
      "env": {
        "CONTROL_PLANE_API_KEY": "your-jwt-token-here",
        "MCP_PROFILE": "prod"
      }
    }
  }
}

{
  "mcpServers": {
    "kubiya-control-plane": {
      "command": "kubiya-mcp",
      "args": [],
      "env": {
        "CONTROL_PLANE_API_KEY": "your-jwt-token-here",
        "MCP_PROFILE": "prod"
      }
    }
  }
}

Replace your-jwt-token-here with your actual Kubiya API key from Step 2.

File location: ~/.config/Claude/claude_desktop_config.json

Using npx
Using global install

{
  "mcpServers": {
    "kubiya-control-plane": {
      "command": "npx",
      "args": ["@kubiya/control-plane-mcp-server"],
      "env": {
        "CONTROL_PLANE_API_KEY": "your-jwt-token-here",
        "MCP_PROFILE": "prod"
      }
    }
  }
}

{
  "mcpServers": {
    "kubiya-control-plane": {
      "command": "kubiya-mcp",
      "args": [],
      "env": {
        "CONTROL_PLANE_API_KEY": "your-jwt-token-here",
        "MCP_PROFILE": "prod"
      }
    }
  }
}

Replace your-jwt-token-here with your actual Kubiya API key from Step 2.

You can customize the server name (kubiya-control-plane) to anything you prefer. This is how it will appear in Claude Desktop.

Step 4: Restart Claude Desktop

Quit Claude Desktop completely (not just close the window)
- macOS: Cmd + Q
- Windows: Right-click taskbar icon → Quit
- Linux: Close all windows
Reopen Claude Desktop
Verify the connection:
- Look for the 🔌 icon in the bottom-right corner
- Click it to see available MCP servers
- You should see “kubiya-control-plane” (or your custom name) listed

If you see the Kubiya MCP Server listed, you’re all set!

Step 5: Try Your First Command

Now you can ask Claude to interact with your Kubiya infrastructure using natural language:

List all agents

Try asking:

“What agents do I have in Kubiya?”

Or:

“List all my Kubiya agents”

Claude will use the list_agents tool to fetch and display your agents.

Get agent details

Try asking:

“Show me details about the [agent-name] agent”

Or:

“What can the DevOps agent do?”

Claude will use the get_agent tool to fetch detailed information.

Execute an agent

Try asking:

“Run the DevOps agent with prompt: check Kubernetes cluster status”

Or:

“Execute the monitoring agent to get system metrics”

Claude will:

Find the agent
Execute it with your prompt
Stream the results back to you

List environments

Try asking:

“What environments are configured in Kubiya?”

Or:

“Show me all environments”

Claude will use the list_environments tool.

Create a new job

Try asking:

“Create a daily job that runs the backup agent at 2 AM UTC”

Claude will use the create_job tool with the appropriate configuration.

What You Can Do

With the Kubiya MCP Server connected, you can:

Manage Agents

List all agents
Get agent details
Create new agents
Update agent configurations
Delete agents
Execute agents with prompts

Manage Teams

List teams
Get team details
Create teams
Update team configurations
Execute team workflows

Monitor Executions

View execution history
Stream execution progress
Get execution details
Track tool usage
Monitor status changes

Configure Infrastructure

Manage environments
Configure worker queues
Set up projects
Define skills
Create policies

Schedule Jobs

Create scheduled jobs
Trigger jobs manually
Update job configurations
Monitor job executions

Manage Workflows

List workflows
Get workflow details
Create workflow definitions

Example Conversation

Here’s an example of what a conversation with Claude might look like:

You: What agents do I have?Claude: Let me check your Kubiya agents.[Uses list_agents tool]You have 3 agents configured:

DevOps Agent
- Purpose: Kubernetes and infrastructure management
- Model: gpt-4
- Skills: kubectl, helm, terraform
Support Agent
- Purpose: Ticket management and user support
- Model: claude-3-5-sonnet
- Skills: jira, slack, zendesk
Monitoring Agent
- Purpose: System health and alerting
- Model: gpt-4
- Skills: prometheus, grafana, pagerduty

You: Run the DevOps agent to check if there are any pending deployments in productionClaude: I’ll execute the DevOps agent for you.[Uses execute_agent tool] [Uses stream_execution_to_completion tool]Execution started…The agent is checking production deployments…Result: Found 2 pending deployments:

api-service v2.3.1 (waiting for approval)
frontend-app v1.5.0 (scheduled for 14:00 UTC)

Both deployments are on hold pending manual approval in the deployment pipeline.

You: Create a staging environmentClaude: I’ll create a staging environment for you.[Uses create_environment tool]Environment created successfully:

Name: staging
ID: env-abc123
Status: active
Created: 2025-12-16 10:30:00 UTC

The staging environment is now ready to use. Would you like me to configure any agents or worker queues for this environment?

Troubleshooting

MCP server doesn't appear in Claude Desktop

Solutions:

Ensure you fully quit and restarted Claude Desktop (not just closed the window)
Check the config file path is correct for your OS
Verify JSON syntax is valid (no trailing commas, quotes correct)
Check Claude Desktop logs:
- macOS: ~/Library/Logs/Claude/mcp*.log
- Windows: %APPDATA%\Claude\logs\mcp*.log
- Linux: ~/.config/Claude/logs/mcp*.log

Connection failed or authentication error

Solutions:

Verify your API key is correct (check for extra spaces)
Ensure MCP_PROFILE is set to "prod" for production

Test the server manually:

export CONTROL_PLANE_API_KEY="your-key"
export MCP_PROFILE="prod"
kubiya-mcp

Check API key hasn’t expired in the dashboard

Claude says tools are not available

Solutions:

Check tool whitelisting (if configured)
Verify the server started successfully (check logs)
Try asking Claude to “list available tools”
Restart Claude Desktop

Execution timeouts or slow responses

Solutions:

Check your internet connection
Verify the Kubiya API is accessible
Use streaming for long-running executions

Enable debug logging:

{
  "mcpServers": {
    "kubiya-control-plane": {
      "env": {
        "LOG_LEVEL": "debug"
      }
    }
  }
}

Advanced Configuration

For more advanced use cases, you can customize the MCP server configuration:

{
  "mcpServers": {
    "kubiya-control-plane": {
      "command": "npx",
      "args": ["@kubiya/control-plane-mcp-server"],
      "env": {
        "CONTROL_PLANE_API_KEY": "your-jwt-token-here",
        "MCP_PROFILE": "prod",
        "LOG_LEVEL": "info",
        "MCP_ALLOWED_TOOLS": "*"
      }
    }
  }
}

Environment Profiles

dev: Local development
staging: Staging environment
prod: Production (default)

Log Levels

debug: Verbose logging
info: Normal logging
warn: Warnings only
error: Errors only

Tool Whitelisting

*: All tools (default)
list_*,get_*: Read-only
list_agents,execute_agent: Specific tools

Custom API URL

Set CONTROL_PLANE_API_URL to override the default endpoint

Learn more about configuration →

Next Steps

Tools Reference

Explore all 54 available tools

Resources

Understand context injection

Configuration

Advanced configuration options

Examples

See practical usage patterns

Need Help?

Documentation: docs.kubiya.ai
GitHub Issues: Report a bug
Email: [email protected]

Getting Started

Reference

Guides

Prerequisites

Step 1: Install the MCP Server

Step 2: Get Your API Key

Step 3: Configure Claude Desktop

Step 4: Restart Claude Desktop

Step 5: Try Your First Command

What You Can Do

Manage Agents

Manage Teams

Monitor Executions

Configure Infrastructure

Schedule Jobs

Manage Workflows

Example Conversation

Troubleshooting

Advanced Configuration

Environment Profiles

Log Levels

Tool Whitelisting

Custom API URL

Next Steps

Tools Reference

Resources

Configuration

Examples

Need Help?

Getting Started

Reference

Guides

​Prerequisites

​Step 1: Install the MCP Server

​Step 2: Get Your API Key

​Step 3: Configure Claude Desktop

​Step 4: Restart Claude Desktop

​Step 5: Try Your First Command

​What You Can Do

Manage Agents

Manage Teams

Monitor Executions

Configure Infrastructure

Schedule Jobs

Manage Workflows

​Example Conversation

​Troubleshooting

​Advanced Configuration

Environment Profiles

Log Levels

Tool Whitelisting

Custom API URL

​Next Steps

Tools Reference

Resources

Configuration

Examples

​Need Help?

Prerequisites

Step 1: Install the MCP Server

Step 2: Get Your API Key

Step 3: Configure Claude Desktop

Step 4: Restart Claude Desktop

Step 5: Try Your First Command

What You Can Do

Example Conversation

Troubleshooting

Advanced Configuration

Next Steps

Need Help?