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

# Tools Reference

> Complete reference for all MCP tools

The Kubiya MCP Server provides specialized tools organized into logical categories. Each tool supports specific operations for managing your Kubiya infrastructure.

## Tool Categories

<CardGroup cols={3}>
  <Card title="Agents" icon="robot" href="#agents" />

  <Card title="Teams" icon="users" href="#teams" />

  <Card title="Executions" icon="play" href="#executions" />

  <Card title="Environments" icon="globe" href="#environments" />

  <Card title="Projects" icon="folder" href="#projects" />

  <Card title="Skills" icon="tools" href="#skills" />

  <Card title="Worker Queues" icon="layer-group" href="#worker-queues" />

  <Card title="Policies" icon="shield-halved" href="#policies" />

  <Card title="Jobs" icon="clock" href="#jobs" />

  <Card title="Workflows" icon="diagram-project" href="#workflows" />

  <Card title="System" icon="server" href="#system" />
</CardGroup>

***

## Agents

Tools for managing AI agents and their configurations.

### list\_agents

List all agents with pagination support.

**Parameters:**

```json theme={null}
{
  "skip": 0,        // Number of items to skip (optional)
  "limit": 10       // Maximum items to return (optional)
}
```

**Example:**

> "List all my agents"
> "Show the first 5 agents"

***

### get\_agent

Get detailed information about a specific agent.

**Parameters:**

```json theme={null}
{
  "id": "agent-uuid"  // Agent ID (required)
}
```

**Example:**

> "Show me details about agent abc-123"
> "Get information for the DevOps agent"

***

### create\_agent

Create a new agent with configuration.

**Parameters:**

```json theme={null}
{
  "name": "My Agent",                    // Agent name (required)
  "description": "Agent description",     // Description (optional)
  "instructions": "You are...",          // System prompt (required)
  "model": "gpt-4",                      // LLM model (optional)
  "project_ids": ["project-uuid"],       // Associated projects (optional)
  "environment_ids": ["env-uuid"],       // Associated environments (optional)
  "skill_ids": ["skill-uuid"],           // Toolsets/skills (optional)
  "runner_config": {...},                // Runner configuration (optional)
  "secrets": {...},                      // Secret values (optional)
  "env_vars": {...}                      // Environment variables (optional)
}
```

**Example:**

> "Create an agent named 'DevOps Helper' that manages Kubernetes"
> "Create a new support agent with Slack integration"

***

### update\_agent

Update an existing agent's configuration.

**Parameters:**

```json theme={null}
{
  "id": "agent-uuid",              // Agent ID (required)
  "name": "Updated Name",          // New name (optional)
  "description": "New description",// New description (optional)
  "instructions": "Updated prompt",// New instructions (optional)
  // ... other agent fields
}
```

**Example:**

> "Update the DevOps agent to use GPT-4"
> "Change the agent description"

***

### delete\_agent

Delete an agent by ID.

**Parameters:**

```json theme={null}
{
  "id": "agent-uuid"  // Agent ID (required)
}
```

**Example:**

> "Delete the test agent"
> "Remove agent abc-123"

<Warning>
  Deleting an agent is permanent and cannot be undone.
</Warning>

***

### execute\_agent

Execute an agent with a prompt.

**Parameters:**

```json theme={null}
{
  "agent_id": "agent-uuid",           // Agent ID (required)
  "prompt": "What is the status?",    // User prompt (required)
  "environment_id": "env-uuid"        // Environment context (optional)
}
```

**Example:**

> "Execute the DevOps agent with prompt: check cluster health"
> "Run the support agent to create a ticket"

<Tip>
  Use `stream_execution_to_completion` to monitor execution progress.
</Tip>

***

## Teams

Tools for managing teams and collaborative workflows.

### list\_teams

List all teams with pagination.

**Parameters:**

```json theme={null}
{
  "skip": 0,
  "limit": 10
}
```

**Example:**

> "Show all teams"
> "List my teams"

***

### get\_team

Get detailed information about a team.

**Parameters:**

```json theme={null}
{
  "id": "team-uuid"
}
```

**Example:**

> "Get details for the DevOps team"

***

### create\_team

Create a new team.

**Parameters:**

```json theme={null}
{
  "name": "My Team",                // Team name (required)
  "description": "Team description",// Description (optional)
  "runtime": "default",             // Runtime type (optional)
  "skill_ids": ["skill-uuid"],      // Toolsets (optional)
  "runner_config": {...}            // Configuration (optional)
}
```

**Example:**

> "Create a team called 'Infrastructure Team'"

***

### update\_team

Update team configuration.

**Parameters:**

```json theme={null}
{
  "id": "team-uuid",
  "name": "Updated Name",
  // ... other team fields
}
```

**Example:**

> "Update the Infrastructure team configuration"

***

### delete\_team

Delete a team by ID.

**Parameters:**

```json theme={null}
{
  "id": "team-uuid"
}
```

**Example:**

> "Delete the test team"

***

### execute\_team

Execute a team with a prompt.

**Parameters:**

```json theme={null}
{
  "team_id": "team-uuid",
  "prompt": "Deploy the application",
  "environment_id": "env-uuid"
}
```

**Example:**

> "Execute the DevOps team to deploy to production"

***

## Executions

Tools for monitoring and managing execution history.

### list\_executions

List execution history with filtering.

**Parameters:**

```json theme={null}
{
  "skip": 0,
  "limit": 10,
  "status": "completed",           // Filter by status (optional)
  "entity_id": "agent-or-team-id"  // Filter by agent/team (optional)
}
```

**Status values:** `pending`, `running`, `completed`, `failed`

**Example:**

> "Show recent executions"
> "List failed executions from the DevOps agent"

***

### get\_execution

Get detailed execution information.

**Parameters:**

```json theme={null}
{
  "execution_id": "exec-uuid"
}
```

**Example:**

> "Show execution details for exec-123"

***

### get\_execution\_messages

Get messages and logs from an execution.

**Parameters:**

```json theme={null}
{
  "execution_id": "exec-uuid"
}
```

**Example:**

> "Get logs from execution exec-123"

***

### stream\_execution\_to\_completion

Stream execution events until completion (batch processing).

**Parameters:**

```json theme={null}
{
  "execution_id": "exec-uuid",
  "timeout_seconds": 270,                    // Max wait time (optional)
  "event_filter": ["tool_started", "done"]   // Event types to include (optional)
}
```

**Event types:**

* `message` - Complete messages
* `message_chunk` - Streaming chunks
* `tool_started` - Tool execution started
* `tool_completed` - Tool finished
* `status` - Status changes
* `done` - Execution completed
* `error` - Error occurred

**Example:**

> "Stream the execution and show me all events"
> "Monitor execution exec-123 until it completes"

<Tip>
  Use this tool for collecting complete execution history. For interactive UIs, use `get_execution_events` instead.
</Tip>

***

### get\_execution\_events

Poll for new execution events incrementally.

**Parameters:**

```json theme={null}
{
  "execution_id": "exec-uuid",
  "last_event_id": "event-123",  // For pagination (optional)
  "limit": 50                    // Max events to return (optional)
}
```

**Example:**

> "Get new events for execution exec-123"
> "Poll for updates on the running execution"

<Tip>
  Use this tool for building interactive UIs that need incremental updates. Call repeatedly with `last_event_id` to get only new events.
</Tip>

***

## Environments

Tools for managing deployment environments.

### list\_environments

List all environments.

**Parameters:**

```json theme={null}
{
  "status_filter": "active"  // Filter by status (optional)
}
```

**Example:**

> "List all environments"
> "Show active environments"

***

### get\_environment

Get environment details.

**Parameters:**

```json theme={null}
{
  "id": "env-uuid"
}
```

**Example:**

> "Get details for the production environment"

***

### create\_environment

Create a new environment.

**Parameters:**

```json theme={null}
{
  "name": "production",                    // Environment name (required)
  "display_name": "Production",           // Display name (optional)
  "description": "Production environment", // Description (optional)
  "tags": ["prod", "main"]                // Tags (optional)
}
```

**Example:**

> "Create a staging environment"
> "Create an environment named 'qa-testing'"

***

### update\_environment

Update environment configuration.

**Parameters:**

```json theme={null}
{
  "id": "env-uuid",
  "display_name": "Updated Name",
  // ... other fields
}
```

**Example:**

> "Update the staging environment description"

***

### delete\_environment

Delete an environment.

**Parameters:**

```json theme={null}
{
  "id": "env-uuid"
}
```

**Example:**

> "Delete the test environment"

***

## Projects

Tools for managing projects.

### list\_projects

List all projects.

**Parameters:**

```json theme={null}
{
  "skip": 0,
  "limit": 10
}
```

**Example:**

> "Show all projects"

***

### get\_project

Get project details.

**Parameters:**

```json theme={null}
{
  "id": "project-uuid"
}
```

**Example:**

> "Get details for project abc-123"

***

### create\_project

Create a new project.

**Parameters:**

```json theme={null}
{
  "name": "My Project",           // Project name (required)
  "key": "MYPROJ",                // Project key (required)
  "description": "Description",    // Description (optional)
  "visibility": "private"          // Visibility (optional)
}
```

**Example:**

> "Create a project called 'Infrastructure Automation'"

***

### update\_project

Update project configuration.

**Parameters:**

```json theme={null}
{
  "id": "project-uuid",
  "name": "Updated Name",
  // ... other fields
}
```

**Example:**

> "Update project INFRA description"

***

### delete\_project

Delete a project.

**Parameters:**

```json theme={null}
{
  "id": "project-uuid"
}
```

**Example:**

> "Delete the test project"

***

## Skills

Tools for managing skills (toolsets).

### list\_skills

List all available skills.

**Parameters:**

```json theme={null}
{
  "skip": 0,
  "limit": 10
}
```

**Example:**

> "Show all available skills"
> "List toolsets"

***

### get\_skill

Get skill details.

**Parameters:**

```json theme={null}
{
  "id": "skill-uuid"
}
```

**Example:**

> "Get details for the kubectl skill"

***

### create\_skill

Create a new skill.

**Parameters:**

```json theme={null}
{
  "name": "File System Access",      // Skill name (required)
  "type": "file_system",             // Skill type (required)
  "description": "File operations",  // Description (optional)
  "enabled": true                    // Enabled status (optional)
}
```

**Example:**

> "Create a skill for GitHub operations"

***

### update\_skill

Update skill configuration.

**Parameters:**

```json theme={null}
{
  "id": "skill-uuid",
  "enabled": false,
  // ... other fields
}
```

**Example:**

> "Disable the deprecated skill"

***

### delete\_skill

Delete a skill.

**Parameters:**

```json theme={null}
{
  "id": "skill-uuid"
}
```

**Example:**

> "Delete the test skill"

***

## Worker Queues

Tools for managing worker queues.

### list\_worker\_queues

List all worker queues.

**Parameters:**

```json theme={null}
{
  "skip": 0,
  "limit": 10
}
```

**Example:**

> "Show all worker queues"
> "List queues"

***

### get\_worker\_queue

Get worker queue details.

**Parameters:**

```json theme={null}
{
  "id": "queue-uuid"
}
```

**Example:**

> "Get details for the production queue"

***

### create\_worker\_queue

Create a new worker queue.

**Parameters:**

```json theme={null}
{
  "environment_id": "env-uuid",        // Environment (required)
  "name": "default-queue",             // Queue name (required)
  "display_name": "Default Queue",     // Display name (optional)
  "max_workers": 10,                   // Max workers (optional)
  "heartbeat_interval": 60             // Heartbeat seconds (optional)
}
```

**Example:**

> "Create a worker queue for the staging environment"

***

### update\_worker\_queue

Update worker queue configuration.

**Parameters:**

```json theme={null}
{
  "id": "queue-uuid",
  "max_workers": 20,
  // ... other fields
}
```

**Example:**

> "Increase max workers to 20 for the production queue"

***

### delete\_worker\_queue

Delete a worker queue.

**Parameters:**

```json theme={null}
{
  "id": "queue-uuid"
}
```

**Example:**

> "Delete the test queue"

***

## Policies

Tools for managing OPA policies.

### list\_policies

List all policies.

**Parameters:**

```json theme={null}
{
  "page": 1,
  "limit": 20,
  "enabled": true  // Filter by enabled status (optional)
}
```

**Example:**

> "Show all policies"
> "List enabled policies"

***

### get\_policy

Get policy details.

**Parameters:**

```json theme={null}
{
  "id": "policy-uuid"
}
```

**Example:**

> "Get the access control policy details"

***

### create\_policy

Create a new OPA policy.

**Parameters:**

```json theme={null}
{
  "name": "Access Control",              // Policy name (required)
  "policy_content": "package kubiya...", // OPA policy code (required)
  "description": "Controls access",      // Description (optional)
  "enabled": true,                       // Enabled status (optional)
  "tags": ["security"]                   // Tags (optional)
}
```

**Example:**

> "Create a policy to restrict production access"

***

### update\_policy

Update policy configuration.

**Parameters:**

```json theme={null}
{
  "id": "policy-uuid",
  "enabled": false,
  // ... other fields
}
```

**Example:**

> "Disable the test policy"

***

### delete\_policy

Delete a policy.

**Parameters:**

```json theme={null}
{
  "id": "policy-uuid"
}
```

**Example:**

> "Delete the deprecated policy"

***

## Jobs

Tools for managing scheduled jobs.

### list\_jobs

List all scheduled jobs.

**Parameters:**

```json theme={null}
{
  "enabled": true,           // Filter by enabled status (optional)
  "trigger_type": "cron"     // Filter by trigger type (optional)
}
```

**Trigger types:** `cron`, `webhook`, `manual`

**Example:**

> "Show all scheduled jobs"
> "List enabled cron jobs"

***

### get\_job

Get job details.

**Parameters:**

```json theme={null}
{
  "id": "job-uuid"
}
```

**Example:**

> "Get details for the daily backup job"

***

### create\_job

Create a new scheduled job.

**Parameters:**

```json theme={null}
{
  "name": "Daily Report",                        // Job name (required)
  "trigger_type": "cron",                        // Trigger type (required)
  "cron_schedule": "0 9 * * *",                  // Cron expression (for cron type)
  "cron_timezone": "America/New_York",           // Timezone (optional)
  "planning_mode": "predefined_agent",           // Planning mode (required)
  "entity_id": "agent-uuid",                     // Agent/team ID (required)
  "prompt_template": "Generate report for {{date}}" // Prompt template (required)
}
```

**Planning modes:**

* `predefined_agent` - Use specific agent
* `predefined_team` - Use specific team

**Example:**

> "Create a daily job that runs the backup agent at 2 AM UTC"
> "Schedule a weekly report generation"

***

### update\_job

Update job configuration.

**Parameters:**

```json theme={null}
{
  "id": "job-uuid",
  "cron_schedule": "0 10 * * *",
  // ... other fields
}
```

**Example:**

> "Change the backup job schedule to 3 AM"

***

### delete\_job

Delete a job.

**Parameters:**

```json theme={null}
{
  "id": "job-uuid"
}
```

**Example:**

> "Delete the test job"

***

### trigger\_job

Manually trigger a job execution.

**Parameters:**

```json theme={null}
{
  "id": "job-uuid",
  "variables": {           // Template variables (optional)
    "date": "2025-01-01"
  }
}
```

**Example:**

> "Trigger the backup job now"
> "Run the report job with date=2025-12-15"

***

## Workflows

Tools for managing workflows.

### list\_workflows

List all workflows.

**Parameters:**

```json theme={null}
{
  "skip": 0,
  "limit": 10
}
```

**Example:**

> "Show all workflows"

***

### get\_workflow

Get workflow details.

**Parameters:**

```json theme={null}
{
  "workflow_id": "workflow-uuid"
}
```

**Example:**

> "Get details for the deployment workflow"

***

### create\_workflow

Create a new workflow definition.

**Parameters:**

```json theme={null}
{
  "name": "Deploy Application",
  "steps": [...],           // Workflow steps
  "description": "..."      // Description (optional)
}
```

**Example:**

> "Create a workflow for deploying to Kubernetes"

***

## System

System health and configuration tools.

### health\_check

Check API health status.

**Parameters:** None

**Example:**

> "Check Kubiya API health"
> "Is the system healthy?"

**Returns:**

* API status
* Response time
* System version

***

### list\_models

List available LLM models.

**Parameters:** None

**Example:**

> "What models are available?"
> "List supported LLMs"

**Returns:**

* Model names (e.g., gpt-4, claude-3-5-sonnet)
* Model capabilities
* Availability status

***

## Tool Whitelisting

Control which tools are available using the `MCP_ALLOWED_TOOLS` environment variable:

```bash theme={null}
# Allow all tools (default)
export MCP_ALLOWED_TOOLS="*"

# Allow specific tools
export MCP_ALLOWED_TOOLS="list_agents,get_agent,execute_agent"

# Use wildcard patterns
export MCP_ALLOWED_TOOLS="list_*,get_*"  # All list and get tools

# Read-only mode
export MCP_ALLOWED_TOOLS="list_*,get_*,health_check"
```

[Learn more about configuration →](/mcp/configuration)

## Next Steps

<CardGroup cols={2}>
  <Card title="Resources" icon="database" href="/mcp/resources">
    Learn about context injection
  </Card>

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

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

  <Card title="Quick Start" icon="rocket" href="/mcp/quick-start">
    Get started with Claude Desktop
  </Card>
</CardGroup>