> ## 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.

# Installation

> Install and set up the Kubiya MCP Server

## Prerequisites

Before installing the Kubiya MCP Server, ensure you have:

<AccordionGroup>
  <Accordion title="Node.js 20 or higher">
    The MCP server requires Node.js version 20.0.0 or higher.

    **Check your version**:

    ```bash theme={null}
    node --version
    ```

    **Install or update Node.js**:

    * **macOS**: `brew install node@20`
    * **Ubuntu/Debian**: `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt-get install -y nodejs`
    * **Windows**: Download from [nodejs.org](https://nodejs.org/)
  </Accordion>

  <Accordion title="Kubiya API Key">
    You need a valid Kubiya API key to authenticate with the Control Plane API.

    **Get your API key**:

    1. Navigate to [Kubiya Dashboard](https://app.kubiya.ai)
    2. Go to **Settings → API Keys**
    3. Click **Create New API Key**
    4. Copy the JWT token

    Store it securely - you'll need it for configuration.
  </Accordion>

  <Accordion title="npm or npx">
    npm is included with Node.js. npx allows running packages without global installation.

    **Verify npm**:

    ```bash theme={null}
    npm --version
    ```
  </Accordion>
</AccordionGroup>

## Installation Methods

### Method 1: Global Installation (Recommended)

Install the MCP server globally to use it from anywhere:

```bash theme={null}
npm install -g @kubiya/control-plane-mcp-server
```

**Verify installation**:

```bash theme={null}
kubiya-mcp --version
```

**Run the server**:

```bash theme={null}
kubiya-mcp
```

<Note>
  Global installation is recommended if you'll use the server frequently or with multiple MCP clients.
</Note>

### Method 2: npx (No Installation)

Run the server without installing using npx:

```bash theme={null}
npx @kubiya/control-plane-mcp-server
```

<Note>
  npx is great for trying the server or using it with Claude Desktop without cluttering your global packages.
</Note>

### Method 3: From Source

Clone and build from source for development or customization:

```bash theme={null}
# Clone the repository
git clone https://github.com/kubiyabot/kubiya-mcp-server.git
cd kubiya-mcp-server

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run the server
npm start
```

<Note>
  Building from source is recommended for contributors or when you need to customize the server.
</Note>

## Configuration

### Set Your API Key

The MCP server requires your Kubiya API key to authenticate with the Control Plane API.

<Tabs>
  <Tab title="macOS / Linux">
    Add to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.):

    ```bash theme={null}
    export CONTROL_PLANE_API_KEY="your-jwt-token-here"
    ```

    **Apply changes**:

    ```bash theme={null}
    source ~/.zshrc  # or ~/.bashrc
    ```
  </Tab>

  <Tab title="Windows (PowerShell)">
    ```powershell theme={null}
    $env:CONTROL_PLANE_API_KEY = "your-jwt-token-here"
    ```

    **For persistent setting**:

    ```powershell theme={null}
    [System.Environment]::SetEnvironmentVariable('CONTROL_PLANE_API_KEY', 'your-jwt-token-here', 'User')
    ```
  </Tab>

  <Tab title="Windows (CMD)">
    ```cmd theme={null}
    set CONTROL_PLANE_API_KEY=your-jwt-token-here
    ```

    **For persistent setting**:

    ```cmd theme={null}
    setx CONTROL_PLANE_API_KEY "your-jwt-token-here"
    ```
  </Tab>
</Tabs>

### Set Environment Profile

Choose your environment (dev, staging, or prod):

```bash theme={null}
export MCP_PROFILE="prod"  # or "dev", "staging"
```

<Info>
  * **dev**: Points to `http://localhost:8000` (for local development)
  * **staging**: Points to `https://staging-control-plane.kubiya.ai`
  * **prod**: Points to `https://control-plane.kubiya.ai` (default for production use)
</Info>

### Optional: Set Log Level

Control logging verbosity:

```bash theme={null}
export LOG_LEVEL="info"  # debug, info, warn, or error
```

## Verify Installation

Test that the server can connect to the Kubiya API:

```bash theme={null}
# Set your API key first
export CONTROL_PLANE_API_KEY="your-jwt-token-here"
export MCP_PROFILE="prod"

# Run the server
kubiya-mcp
```

**Expected output**:

```
🚀 Starting Kubiya Control Plane MCP Server...
✅ Configuration loaded successfully
✅ API client initialized
✅ Registered 54 tools across 11 categories
✅ Registered 8 resources for context injection
✨ MCP Server running on stdio
🎯 Ready to accept requests
```

<Check>
  If you see this output, the server is successfully installed and configured!
</Check>

## Test with MCP Inspector

The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a development tool for testing MCP servers:

```bash theme={null}
npx @modelcontextprotocol/inspector npx @kubiya/control-plane-mcp-server
```

This opens a web interface where you can:

* Browse available tools
* Test tool execution
* View resources
* Inspect responses

<Tip>
  The MCP Inspector is great for debugging and understanding what the server provides before integrating with an AI assistant.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Error: Configuration validation failed: API key is required">
    **Problem**: The `CONTROL_PLANE_API_KEY` environment variable is not set.

    **Solution**:

    ```bash theme={null}
    export CONTROL_PLANE_API_KEY="your-jwt-token-here"
    ```

    Verify it's set:

    ```bash theme={null}
    echo $CONTROL_PLANE_API_KEY
    ```
  </Accordion>

  <Accordion title="Error: Failed to connect to API">
    **Problem**: Network connectivity issue or incorrect API URL.

    **Solutions**:

    1. Check your internet connection
    2. Verify the profile is correct:
       ```bash theme={null}
       export MCP_PROFILE="prod"
       ```
    3. Enable debug logging:
       ```bash theme={null}
       export LOG_LEVEL="debug"
       kubiya-mcp
       ```
    4. Check firewall settings allow outbound HTTPS
  </Accordion>

  <Accordion title="Error: Authentication failed (401)">
    **Problem**: Invalid or expired API key.

    **Solutions**:

    1. Verify your API key is valid:
       * Go to [Kubiya Dashboard](https://app.kubiya.ai) → Settings → API Keys
       * Check the key hasn't expired
       * Generate a new key if needed
    2. Ensure you're using the correct environment (dev/staging/prod)
    3. Check for extra spaces or quotes in the key
  </Accordion>

  <Accordion title="Error: Command not found: kubiya-mcp">
    **Problem**: Global installation path not in your PATH.

    **Solutions**:

    1. Use npx instead:
       ```bash theme={null}
       npx @kubiya/control-plane-mcp-server
       ```
    2. Check npm global bin location:
       ```bash theme={null}
       npm config get prefix
       ```
    3. Add npm global bin to PATH:
       ```bash theme={null}
       export PATH="$(npm config get prefix)/bin:$PATH"
       ```
  </Accordion>

  <Accordion title="Error: EACCES permission denied">
    **Problem**: Permission issues with global npm installation.

    **Solutions**:

    1. Use npx (no permissions needed):
       ```bash theme={null}
       npx @kubiya/control-plane-mcp-server
       ```
    2. Configure npm to use a different directory:
       ```bash theme={null}
       mkdir ~/.npm-global
       npm config set prefix '~/.npm-global'
       export PATH=~/.npm-global/bin:$PATH
       npm install -g @kubiya/control-plane-mcp-server
       ```
    3. Use a Node version manager like [nvm](https://github.com/nvm-sh/nvm)
  </Accordion>
</AccordionGroup>

## Upgrade

### Upgrade Global Installation

```bash theme={null}
npm update -g @kubiya/control-plane-mcp-server
```

### Upgrade Source Installation

```bash theme={null}
cd kubiya-mcp-server
git pull
npm install
npm run build
```

### Check Current Version

```bash theme={null}
# Global installation
kubiya-mcp --version

# npx
npx @kubiya/control-plane-mcp-server --version

# Check installed package
npm list -g @kubiya/control-plane-mcp-server
```

## Uninstall

### Uninstall Global Installation

```bash theme={null}
npm uninstall -g @kubiya/control-plane-mcp-server
```

### Remove Source Installation

```bash theme={null}
rm -rf kubiya-mcp-server
```

### Clean Environment Variables

Remove from your shell profile:

```bash theme={null}
# Remove these lines from ~/.bashrc or ~/.zshrc
# export CONTROL_PLANE_API_KEY="..."
# export MCP_PROFILE="..."
# export LOG_LEVEL="..."
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/mcp/quick-start">
    Connect to Claude Desktop and start using the server
  </Card>

  <Card title="Configuration" icon="gear" href="/mcp/configuration">
    Learn about advanced configuration options
  </Card>

  <Card title="Tools Reference" icon="book" href="/mcp/tools-reference">
    Explore all available tools
  </Card>

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