Skip to main content

​
Prerequisites

Before installing the Kubiya MCP Server, ensure you have:
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
You need a valid Kubiya API key to authenticate with the Control Plane API.Get your API key:
  1. Navigate to Kubiya Dashboard
  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.
npm is included with Node.js. npx allows running packages without global installation.Verify npm:
npm --version

​
Installation Methods

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.
Add to your shell profile (~/.bashrc, ~/.zshrc, etc.):
export CONTROL_PLANE_API_KEY="your-jwt-token-here"
Apply changes:
source ~/.zshrc  # or ~/.bashrc

​
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

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
Problem: Network connectivity issue or incorrect API URL.Solutions:
  1. Check your internet connection
  2. Verify the profile is correct: 
    export MCP_PROFILE="prod"
  3. Enable debug logging: 
    export LOG_LEVEL="debug"
kubiya-mcp
  4. Check firewall settings allow outbound HTTPS
Problem: Invalid or expired API key.Solutions:
  1. 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
  2. Ensure you’re using the correct environment (dev/staging/prod)
  3. Check for extra spaces or quotes in the key
Problem: Global installation path not in your PATH.Solutions:
  1. Use npx instead: 
    npx @kubiya/control-plane-mcp-server
  2. Check npm global bin location: 
    npm config get prefix
  3. Add npm global bin to PATH: 
    export PATH="$(npm config get prefix)/bin:$PATH"
Problem: Permission issues with global npm installation.Solutions:
  1. Use npx (no permissions needed): 
    npx @kubiya/control-plane-mcp-server
  2. 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
  3. 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