> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Get started with the Kubiya MCP Server in minutes

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:

<Check>
  * [ ] Node.js 20+ installed
  * [ ] Kubiya API key from the [dashboard](https://app.kubiya.ai)
  * [ ] Claude Desktop installed ([download here](https://claude.ai/download))
</Check>

## Step 1: Install the MCP Server

Choose your preferred installation method:

<Tabs>
  <Tab title="Global Install">
    ```bash theme={null}
    npm install -g @kubiya/control-plane-mcp-server
    ```
  </Tab>

  <Tab title="npx (No Install)">
    No installation needed! npx will download and run the server automatically.

    Skip to Step 2.
  </Tab>
</Tabs>

## Step 2: Get Your API Key

1. Navigate to the [Kubiya Dashboard](https://app.kubiya.ai)
2. Click on **Settings** in the left sidebar
3. Select **API Keys**
4. Click **Create New API Key**
5. Copy the generated JWT token

<Warning>
  Store your API key securely. Don't commit it to version control or share it publicly.
</Warning>

## Step 3: Configure Claude Desktop

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

<Tabs>
  <Tab title="macOS">
    **File location**: `~/Library/Application Support/Claude/claude_desktop_config.json`

    <Tabs>
      <Tab title="Using npx">
        ```json theme={null}
        {
          "mcpServers": {
            "kubiya-control-plane": {
              "command": "npx",
              "args": ["@kubiya/control-plane-mcp-server"],
              "env": {
                "CONTROL_PLANE_API_KEY": "your-jwt-token-here",
                "MCP_PROFILE": "prod"
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="Using global install">
        ```json theme={null}
        {
          "mcpServers": {
            "kubiya-control-plane": {
              "command": "kubiya-mcp",
              "args": [],
              "env": {
                "CONTROL_PLANE_API_KEY": "your-jwt-token-here",
                "MCP_PROFILE": "prod"
              }
            }
          }
        }
        ```
      </Tab>
    </Tabs>

    <Note>
      Replace `your-jwt-token-here` with your actual Kubiya API key from Step 2.
    </Note>
  </Tab>

  <Tab title="Windows">
    **File location**: `%APPDATA%\Claude\claude_desktop_config.json`

    <Tabs>
      <Tab title="Using npx">
        ```json theme={null}
        {
          "mcpServers": {
            "kubiya-control-plane": {
              "command": "npx",
              "args": ["@kubiya/control-plane-mcp-server"],
              "env": {
                "CONTROL_PLANE_API_KEY": "your-jwt-token-here",
                "MCP_PROFILE": "prod"
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="Using global install">
        ```json theme={null}
        {
          "mcpServers": {
            "kubiya-control-plane": {
              "command": "kubiya-mcp",
              "args": [],
              "env": {
                "CONTROL_PLANE_API_KEY": "your-jwt-token-here",
                "MCP_PROFILE": "prod"
              }
            }
          }
        }
        ```
      </Tab>
    </Tabs>

    <Note>
      Replace `your-jwt-token-here` with your actual Kubiya API key from Step 2.
    </Note>
  </Tab>

  <Tab title="Linux">
    **File location**: `~/.config/Claude/claude_desktop_config.json`

    <Tabs>
      <Tab title="Using npx">
        ```json theme={null}
        {
          "mcpServers": {
            "kubiya-control-plane": {
              "command": "npx",
              "args": ["@kubiya/control-plane-mcp-server"],
              "env": {
                "CONTROL_PLANE_API_KEY": "your-jwt-token-here",
                "MCP_PROFILE": "prod"
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="Using global install">
        ```json theme={null}
        {
          "mcpServers": {
            "kubiya-control-plane": {
              "command": "kubiya-mcp",
              "args": [],
              "env": {
                "CONTROL_PLANE_API_KEY": "your-jwt-token-here",
                "MCP_PROFILE": "prod"
              }
            }
          }
        }
        ```
      </Tab>
    </Tabs>

    <Note>
      Replace `your-jwt-token-here` with your actual Kubiya API key from Step 2.
    </Note>
  </Tab>
</Tabs>

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

## Step 4: Restart Claude Desktop

1. **Quit Claude Desktop completely** (not just close the window)
   * macOS: `Cmd + Q`
   * Windows: Right-click taskbar icon → Quit
   * Linux: Close all windows

2. **Reopen Claude Desktop**

3. **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

<Check>
  If you see the Kubiya MCP Server listed, you're all set!
</Check>

## Step 5: Try Your First Command

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

<AccordionGroup>
  <Accordion title="List all agents" icon="robot">
    **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.
  </Accordion>

  <Accordion title="Get agent details" icon="info">
    **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.
  </Accordion>

  <Accordion title="Execute an agent" icon="play">
    **Try asking**:

    > "Run the DevOps agent with prompt: check Kubernetes cluster status"

    **Or**:

    > "Execute the monitoring agent to get system metrics"

    Claude will:

    1. Find the agent
    2. Execute it with your prompt
    3. Stream the results back to you
  </Accordion>

  <Accordion title="List environments" icon="globe">
    **Try asking**:

    > "What environments are configured in Kubiya?"

    **Or**:

    > "Show me all environments"

    Claude will use the `list_environments` tool.
  </Accordion>

  <Accordion title="Create a new job" icon="clock">
    **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.
  </Accordion>
</AccordionGroup>

## What You Can Do

With the Kubiya MCP Server connected, you can:

<CardGroup cols={2}>
  <Card title="Manage Agents" icon="robot">
    * List all agents
    * Get agent details
    * Create new agents
    * Update agent configurations
    * Delete agents
    * Execute agents with prompts
  </Card>

  <Card title="Manage Teams" icon="users">
    * List teams
    * Get team details
    * Create teams
    * Update team configurations
    * Execute team workflows
  </Card>

  <Card title="Monitor Executions" icon="chart-line">
    * View execution history
    * Stream execution progress
    * Get execution details
    * Track tool usage
    * Monitor status changes
  </Card>

  <Card title="Configure Infrastructure" icon="server">
    * Manage environments
    * Configure worker queues
    * Set up projects
    * Define skills
    * Create policies
  </Card>

  <Card title="Schedule Jobs" icon="calendar">
    * Create scheduled jobs
    * Trigger jobs manually
    * Update job configurations
    * Monitor job executions
  </Card>

  <Card title="Manage Workflows" icon="diagram-project">
    * List workflows
    * Get workflow details
    * Create workflow definitions
  </Card>
</CardGroup>

## Example Conversation

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

<Frame>
  <div style={{padding: '20px', backgroundColor: '#f9fafb', borderRadius: '8px'}}>
    **You**: What agents do I have?

    **Claude**: Let me check your Kubiya agents.

    *\[Uses list\_agents tool]*

    You have 3 agents configured:

    1. **DevOps Agent**
       * Purpose: Kubernetes and infrastructure management
       * Model: gpt-4
       * Skills: kubectl, helm, terraform

    2. **Support Agent**
       * Purpose: Ticket management and user support
       * Model: claude-3-5-sonnet
       * Skills: jira, slack, zendesk

    3. **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 production

    **Claude**: 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 environment

    **Claude**: 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?
  </div>
</Frame>

## Troubleshooting

<AccordionGroup>
  <Accordion title="MCP server doesn't appear in Claude Desktop">
    **Solutions**:

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

  <Accordion title="Connection failed or authentication error">
    **Solutions**:

    1. Verify your API key is correct (check for extra spaces)
    2. Ensure `MCP_PROFILE` is set to `"prod"` for production
    3. Test the server manually:
       ```bash theme={null}
       export CONTROL_PLANE_API_KEY="your-key"
       export MCP_PROFILE="prod"
       kubiya-mcp
       ```
    4. Check API key hasn't expired in the [dashboard](https://app.kubiya.ai)
  </Accordion>

  <Accordion title="Claude says tools are not available">
    **Solutions**:

    1. Check tool whitelisting (if configured)
    2. Verify the server started successfully (check logs)
    3. Try asking Claude to "list available tools"
    4. Restart Claude Desktop
  </Accordion>

  <Accordion title="Execution timeouts or slow responses">
    **Solutions**:

    1. Check your internet connection
    2. Verify the Kubiya API is accessible
    3. Use streaming for long-running executions
    4. Enable debug logging:
       ```json theme={null}
       {
         "mcpServers": {
           "kubiya-control-plane": {
             "env": {
               "LOG_LEVEL": "debug"
             }
           }
         }
       }
       ```
  </Accordion>
</AccordionGroup>

## Advanced Configuration

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

```json theme={null}
{
  "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": "*"
      }
    }
  }
}
```

<CardGroup cols={2}>
  <Card title="Environment Profiles">
    * `dev`: Local development
    * `staging`: Staging environment
    * `prod`: Production (default)
  </Card>

  <Card title="Log Levels">
    * `debug`: Verbose logging
    * `info`: Normal logging
    * `warn`: Warnings only
    * `error`: Errors only
  </Card>

  <Card title="Tool Whitelisting">
    * `*`: All tools (default)
    * `list_*,get_*`: Read-only
    * `list_agents,execute_agent`: Specific tools
  </Card>

  <Card title="Custom API URL">
    Set `CONTROL_PLANE_API_URL` to override the default endpoint
  </Card>
</CardGroup>

[Learn more about configuration →](/mcp/configuration)

## Next Steps

<CardGroup cols={2}>
  <Card title="Tools Reference" icon="book" href="/mcp/tools-reference">
    Explore all 54 available tools
  </Card>

  <Card title="Resources" icon="database" href="/mcp/resources">
    Understand context injection
  </Card>

  <Card title="Configuration" icon="gear" href="/mcp/configuration">
    Advanced configuration options
  </Card>

  <Card title="Examples" icon="lightbulb" href="/mcp/examples">
    See practical usage patterns
  </Card>
</CardGroup>

## Need Help?

* **Documentation**: [docs.kubiya.ai](https://docs.kubiya.ai)
* **GitHub Issues**: [Report a bug](https://github.com/kubiyabot/kubiya-mcp-server/issues)
* **Email**: [support@kubiya.ai](mailto:support@kubiya.ai)