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

# Kubiya MCP Server

> Model Context Protocol server for comprehensive Kubiya platform integration

The Kubiya MCP Server is a production-ready [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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

<CardGroup cols={2}>
  <Card title="Specialized Tools" icon="wrench">
    Complete CRUD operations for agents, teams, environments, projects, skills, worker queues, policies, jobs, workflows, and executions
  </Card>

  <Card title="Dynamic Resources" icon="database">
    Context injection for agents, teams, worker queues, environments, projects, skills, policies, and jobs
  </Card>

  <Card title="Real-time Streaming" icon="bolt">
    SSE-based execution monitoring with automatic reconnection and event filtering
  </Card>

  <Card title="Production Ready" icon="shield-check">
    Enhanced error handling, retry logic, exponential backoff, and proper timeouts
  </Card>

  <Card title="Multi-Environment" icon="server">
    Dev, staging, and production profile support with custom configuration
  </Card>

  <Card title="Security Controls" icon="lock">
    Tool whitelisting, pattern matching, and read-only mode support
  </Card>

  <Card title="Type Safe" icon="code">
    Built with TypeScript and Zod validation for reliability
  </Card>

  <Card title="Easy Integration" icon="puzzle-piece">
    Works with Claude Desktop, MCP Inspector, and any MCP-compatible client
  </Card>
</CardGroup>

## Quick Example

Once installed and configured, you can ask Claude Desktop natural language questions that interact with your Kubiya infrastructure:

<AccordionGroup>
  <Accordion title="List all agents">
    **You ask**: "What agents do I have?"

    **Claude uses**: `list_agents` tool

    **Result**: A formatted list of all your agents with their descriptions and capabilities
  </Accordion>

  <Accordion title="Execute an agent">
    **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
  </Accordion>

  <Accordion title="Create a new environment">
    **You ask**: "Create a staging environment named 'staging-v2' with tags 'test' and 'preview'"

    **Claude uses**: `create_environment` tool

    **Result**: New environment created and ID returned
  </Accordion>

  <Accordion title="Monitor job executions">
    **You ask**: "Show me the last 5 job executions and their status"

    **Claude uses**: `list_executions` tool with filtering

    **Result**: Execution history with status, timestamps, and results
  </Accordion>
</AccordionGroup>

## Architecture

```mermaid theme={null}
graph TB
    subgraph "AI Assistant"
        CLAUDE[Claude Desktop]
        OTHER[Other MCP Clients]
    end

    subgraph "MCP Server"
        SERVER[Kubiya MCP Server]
        TOOLS[Specialized Tools]
        RESOURCES[Dynamic Resources]
        STREAM[Streaming Engine]
    end

    subgraph "Kubiya Platform"
        API[Control Plane API]
        AGENTS[Agents & Teams]
        EXEC[Execution Engine]
        QUEUES[Worker Queues]
    end

    CLAUDE --> SERVER
    OTHER --> SERVER
    SERVER --> TOOLS
    SERVER --> RESOURCES
    SERVER --> STREAM
    TOOLS --> API
    RESOURCES --> API
    STREAM --> API
    API --> AGENTS
    API --> EXEC
    API --> QUEUES

    style CLAUDE fill:#8B5CF6
    style SERVER fill:#10B981
    style API fill:#3B82F6
    style AGENTS fill:#F59E0B
```

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

<CardGroup cols={3}>
  <Card title="Agents" icon="robot">
    Agent lifecycle management
  </Card>

  <Card title="Teams" icon="users">
    Team operations
  </Card>

  <Card title="Environments" icon="globe">
    Environment management
  </Card>

  <Card title="Projects" icon="folder">
    Project administration
  </Card>

  <Card title="Skills" icon="tools">
    Toolset management
  </Card>

  <Card title="Worker Queues" icon="layer-group">
    Queue operations
  </Card>

  <Card title="Policies" icon="shield-halved">
    Policy control
  </Card>

  <Card title="Jobs" icon="clock">
    Job scheduling
  </Card>

  <Card title="Executions" icon="play">
    Execution monitoring
  </Card>

  <Card title="Workflows" icon="diagram-project">
    Workflow operations
  </Card>

  <Card title="System" icon="server">
    Health and configuration
  </Card>
</CardGroup>

[View complete tools reference →](/mcp/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 →](/mcp/resources)

## Getting Started

<Steps>
  <Step title="Install the MCP Server">
    Install via npm or from source

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

    [Installation guide →](/mcp/installation)
  </Step>

  <Step title="Configure Authentication">
    Set your Kubiya API key

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

    [Get your API key from the dashboard](https://app.kubiya.ai)
  </Step>

  <Step title="Integrate with Claude Desktop">
    Add to your Claude Desktop configuration

    ```json theme={null}
    {
      "mcpServers": {
        "kubiya": {
          "command": "npx",
          "args": ["@kubiya/control-plane-mcp-server"],
          "env": {
            "CONTROL_PLANE_API_KEY": "your-key-here"
          }
        }
      }
    }
    ```

    [Quick start guide →](/mcp/quick-start)
  </Step>

  <Step title="Start Using">
    Ask Claude natural language questions about your Kubiya infrastructure
  </Step>
</Steps>

## 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 →](/mcp/configuration)

## Streaming Capabilities

Two complementary approaches for monitoring long-running executions:

<CardGroup cols={2}>
  <Card title="Complete History" icon="list">
    Use `stream_execution_to_completion` to collect all events until the execution finishes
  </Card>

  <Card title="Incremental Polling" icon="arrows-rotate">
    Use `get_execution_events` to poll for updates periodically for interactive UIs
  </Card>
</CardGroup>

Both methods support:

* Event filtering (tool\_started, tool\_completed, done, etc.)
* Automatic reconnection on connection loss
* Gap detection and warnings
* Timeout handling

## Next Steps

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/mcp/installation">
    Get the MCP server installed and running
  </Card>

  <Card title="Quick Start" icon="rocket" href="/mcp/quick-start">
    Connect to Claude Desktop in minutes
  </Card>

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

  <Card title="Configuration" icon="gear" href="/mcp/configuration">
    Configure environments and security
  </Card>

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

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

## Support

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