Installation

Prerequisites

Before installing the Kubiya MCP Server, ensure you have:

Node.js 20 or higher

The MCP server requires Node.js version 20.0.0 or higher.Check your version:

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

Kubiya API Key

You need a valid Kubiya API key to authenticate with the Control Plane API.Get your API key:

Navigate to Kubiya Dashboard
Go to Settings → API Keys
Click Create New API Key
Copy the JWT token

Store it securely - you’ll need it for configuration.

npm or npx

npm is included with Node.js. npx allows running packages without global installation.Verify npm:

npm --version

Installation Methods

Method 1: Global Installation (Recommended)

Install the MCP server globally to use it from anywhere:

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

Verify installation:

kubiya-mcp --version

Run the server:

kubiya-mcp

Global installation is recommended if you’ll use the server frequently or with multiple MCP clients.

Method 2: npx (No Installation)

Run the server without installing using npx:

npx @kubiya/control-plane-mcp-server

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

Method 3: From Source

Clone and build from source for development or customization:

# 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

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

Configuration

Set Your API Key

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

macOS / Linux
Windows (PowerShell)
Windows (CMD)

Add to your shell profile (~/.bashrc, ~/.zshrc, etc.):

export CONTROL_PLANE_API_KEY="your-jwt-token-here"

Apply changes:

source ~/.zshrc  # or ~/.bashrc

$env:CONTROL_PLANE_API_KEY = "your-jwt-token-here"

For persistent setting:

[System.Environment]::SetEnvironmentVariable('CONTROL_PLANE_API_KEY', 'your-jwt-token-here', 'User')

set CONTROL_PLANE_API_KEY=your-jwt-token-here

For persistent setting:

setx CONTROL_PLANE_API_KEY "your-jwt-token-here"

Set Environment Profile

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

export MCP_PROFILE="prod"  # or "dev", "staging"

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)

Optional: Set Log Level

Control logging verbosity:

export LOG_LEVEL="info"  # debug, info, warn, or error

Verify Installation

Test that the server can connect to the Kubiya API:

# 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

If you see this output, the server is successfully installed and configured!

Test with MCP Inspector

The MCP Inspector is a development tool for testing MCP servers:

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

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

Troubleshooting

Error: Configuration validation failed: API key is required

Problem: The CONTROL_PLANE_API_KEY environment variable is not set.Solution:

export CONTROL_PLANE_API_KEY="your-jwt-token-here"

Verify it’s set:

echo $CONTROL_PLANE_API_KEY

Error: Failed to connect to API

Problem: Network connectivity issue or incorrect API URL.Solutions:

Check your internet connection
Verify the profile is correct:
export MCP_PROFILE="prod"
Enable debug logging:
export LOG_LEVEL="debug" kubiya-mcp
Check firewall settings allow outbound HTTPS

Error: Authentication failed (401)

Problem: Invalid or expired API key.Solutions:

Verify your API key is valid:
- Go to Kubiya Dashboard → Settings → API Keys
- Check the key hasn’t expired
- Generate a new key if needed
Ensure you’re using the correct environment (dev/staging/prod)
Check for extra spaces or quotes in the key

Error: Command not found: kubiya-mcp

Problem: Global installation path not in your PATH.Solutions:

Use npx instead:
npx @kubiya/control-plane-mcp-server
Check npm global bin location:
npm config get prefix

Add npm global bin to PATH:

export PATH="$(npm config get prefix)/bin:$PATH"

Error: EACCES permission denied

Problem: Permission issues with global npm installation.Solutions:

Use npx (no permissions needed):
npx @kubiya/control-plane-mcp-server

Configure npm to use a different directory:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
npm install -g @kubiya/control-plane-mcp-server

Use a Node version manager like nvm

Upgrade

Upgrade Global Installation

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

Upgrade Source Installation

cd kubiya-mcp-server
git pull
npm install
npm run build

Check Current Version

# 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

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

Remove Source Installation

rm -rf kubiya-mcp-server

Clean Environment Variables

Remove from your shell profile:

# Remove these lines from ~/.bashrc or ~/.zshrc
# export CONTROL_PLANE_API_KEY="..."
# export MCP_PROFILE="..."
# export LOG_LEVEL="..."

Next Steps

Quick Start

Connect to Claude Desktop and start using the server

Configuration

Learn about advanced configuration options

Tools Reference

Explore all available tools

Examples

See practical usage examples

Getting Started

Reference

Guides

Prerequisites

Installation Methods

Method 1: Global Installation (Recommended)

Method 2: npx (No Installation)

Method 3: From Source

Configuration

Set Your API Key

Set Environment Profile

Optional: Set Log Level

Verify Installation

Test with MCP Inspector

Troubleshooting

Upgrade

Upgrade Global Installation

Upgrade Source Installation

Check Current Version

Uninstall

Uninstall Global Installation

Remove Source Installation

Clean Environment Variables

Next Steps

Quick Start

Configuration

Tools Reference

Examples

​Prerequisites

​Installation Methods

​Method 1: Global Installation (Recommended)

​Method 2: npx (No Installation)

​Method 3: From Source

​Configuration

​Set Your API Key

​Set Environment Profile

​Optional: Set Log Level

​Verify Installation

​Test with MCP Inspector

​Troubleshooting

​Upgrade

​Upgrade Global Installation

​Upgrade Source Installation

​Check Current Version

​Uninstall

​Uninstall Global Installation

​Remove Source Installation

​Clean Environment Variables

​Next Steps

Quick Start

Configuration

Tools Reference

Examples

Prerequisites

Installation Methods

Method 1: Global Installation (Recommended)

Method 2: npx (No Installation)

Method 3: From Source

Configuration

Set Your API Key

Set Environment Profile

Optional: Set Log Level

Verify Installation

Test with MCP Inspector

Troubleshooting

Upgrade

Upgrade Global Installation

Upgrade Source Installation

Check Current Version

Uninstall

Uninstall Global Installation

Remove Source Installation

Clean Environment Variables

Next Steps