Skip to main content
The Kubiya MCP Server is a production-ready Model Context Protocol (MCP) server that provides comprehensive access to the Kubiya Agent Control Plane API. It enables AI assistants like Claude Desktop to interact with your Kubiya infrastructure through specialized tools and dynamic resources.

​
What is MCP?

The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to Large Language Models (LLMs). MCP servers expose capabilities (tools) and data (resources) that AI assistants can use to perform actions and retrieve information.

​
Key Features

Specialized Tools

Complete CRUD operations for agents, teams, environments, projects, skills, worker queues, policies, jobs, workflows, and executions

Dynamic Resources

Context injection for agents, teams, worker queues, environments, projects, skills, policies, and jobs

Real-time Streaming

SSE-based execution monitoring with automatic reconnection and event filtering

Production Ready

Enhanced error handling, retry logic, exponential backoff, and proper timeouts

Multi-Environment

Dev, staging, and production profile support with custom configuration

Security Controls

Tool whitelisting, pattern matching, and read-only mode support

Type Safe

Built with TypeScript and Zod validation for reliability

Easy Integration

Works with Claude Desktop, MCP Inspector, and any MCP-compatible client

​
Quick Example

Once installed and configured, you can ask Claude Desktop natural language questions that interact with your Kubiya infrastructure:
You ask: “What agents do I have?”Claude uses: list_agents toolResult: A formatted list of all your agents with their descriptions and capabilities
You ask: “Run the DevOps agent to check the status of our production Kubernetes cluster”Claude uses:
  1. list_agents to find the DevOps agent
  2. execute_agent to run it with your prompt
  3. stream_execution_to_completion to monitor progress
Result: Real-time execution updates and final results from the agent
You ask: “Create a staging environment named ‘staging-v2’ with tags ‘test’ and ‘preview’”Claude uses: create_environment toolResult: New environment created and ID returned
You ask: “Show me the last 5 job executions and their status”Claude uses: list_executions tool with filteringResult: Execution history with status, timestamps, and results

​
Architecture

​
Use Cases

​
Development & Operations

  • Infrastructure Management: Create and manage agents, teams, and environments
  • Execution Monitoring: Track workflow and agent executions in real-time
  • Queue Management: Monitor and configure worker queues
  • Policy Administration: Create and manage OPA policies for access control

​
Automation

  • Job Scheduling: Create and trigger scheduled jobs
  • Workflow Orchestration: List and execute workflows
  • Agent Execution: Run agents with custom prompts and monitor results
  • Team Collaboration: Execute team-based workflows

​
Monitoring & Analytics

  • Execution History: Query past executions with filtering
  • Real-time Streaming: Monitor long-running executions with SSE
  • Health Checks: Verify API and system health
  • Event Tracking: Track tool executions and status changes

​
Tool Categories

The MCP server organizes tools into logical categories:

Agents

Agent lifecycle management

Teams

Team operations

Environments

Environment management

Projects

Project administration

Skills

Toolset management

Worker Queues

Queue operations

Policies

Policy control

Jobs

Job scheduling

Executions

Execution monitoring

Workflows

Workflow operations

System

Health and configuration
View complete tools reference →

​
Resources

Resources provide dynamic context data that helps AI assistants make informed decisions:
  • agents://list - Available agents with configurations
  • teams://list - Team configurations and members
  • worker-queues://list - Queue status and workers
  • environments://list - Environment configurations
  • projects://list - Project metadata
  • skills://list - Available toolsets
  • policies://list - OPA policies
  • jobs://list - Scheduled jobs
Learn more about resources →

​
Getting Started

1

Install the MCP Server

Install via npm or from source
npm install -g @kubiya/control-plane-mcp-server
Installation guide →
2

Configure Authentication

Set your Kubiya API key
export CONTROL_PLANE_API_KEY="your-jwt-token"
Get your API key from the dashboard
3

Integrate with Claude Desktop

Add to your Claude Desktop configuration
{
  "mcpServers": {
    "kubiya": {
      "command": "npx",
      "args": ["@kubiya/control-plane-mcp-server"],
      "env": {
        "CONTROL_PLANE_API_KEY": "your-key-here"
      }
    }
  }
}
Quick start guide →
4

Start Using

Ask Claude natural language questions about your Kubiya infrastructure

​
Configuration

The MCP server supports flexible configuration:
  • Environment Profiles: Dev, staging, production
  • Tool Whitelisting: Control which tools are available
  • Custom API URLs: Override default endpoints
  • Logging Levels: Debug, info, warn, error
  • Security Controls: Read-only mode, pattern matching
Configuration guide →

​
Streaming Capabilities

Two complementary approaches for monitoring long-running executions:

Complete History

Use stream_execution_to_completion to collect all events until the execution finishes

Incremental Polling

Use get_execution_events to poll for updates periodically for interactive UIs
Both methods support:
  • Event filtering (tool_started, tool_completed, done, etc.)
  • Automatic reconnection on connection loss
  • Gap detection and warnings
  • Timeout handling

​
Next Steps

Installation

Get the MCP server installed and running

Quick Start

Connect to Claude Desktop in minutes

Tools Reference

Explore all available tools

Configuration

Configure environments and security

Resources

Understand context injection

Examples

See real-world usage patterns

​
Support