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

# Resources

> Dynamic context injection with MCP resources

Resources in the Model Context Protocol provide dynamic context data that AI assistants can access to make informed decisions. The Kubiya MCP Server exposes 8 resources that automatically stay up-to-date with your infrastructure.

## What Are MCP Resources?

Resources are read-only data sources that provide context to AI assistants. Unlike tools (which perform actions), resources answer the question: "What information is available?"

When Claude Desktop (or another MCP client) needs to understand your Kubiya infrastructure, it can read these resources to get current state information without making tool calls.

## Benefits

<CardGroup cols={2}>
  <Card title="Automatic Context" icon="sparkles">
    AI assistants automatically have access to current infrastructure state
  </Card>

  <Card title="Reduced Errors" icon="shield-check">
    Valid IDs and configurations prevent mistakes when using tools
  </Card>

  <Card title="Better Decisions" icon="brain">
    AI can make informed choices about which tools to use and with what parameters
  </Card>

  <Card title="Always Fresh" icon="refresh">
    Resources are fetched on-demand, always reflecting current state
  </Card>
</CardGroup>

## Available Resources

### agents\://list

**Description**: List of all available agents with their configurations and capabilities.

**Includes**:

* Agent ID, name, description
* Model configuration (GPT-4, Claude, etc.)
* Instructions/system prompts
* Associated skills and tools
* Environment configurations
* Runner settings
* Secrets and environment variables

**Usage**:
When you ask Claude to execute an agent, it first reads this resource to:

* Find the correct agent ID
* Understand the agent's capabilities
* Verify the agent exists

**Example conversation**:

> **You**: "Run the DevOps agent to check cluster health"
>
> **Claude**:
>
> 1. Reads `agents://list` resource
> 2. Finds "DevOps Agent" with ID `agent-abc123`
> 3. Calls `execute_agent` with ID `agent-abc123`

***

### teams\://list

**Description**: List of all teams with members, skills, and configurations.

**Includes**:

* Team ID, name, description
* Team members (agents)
* Associated skills and toolsets
* Runtime configuration
* Communication settings
* Environment associations

**Usage**:
When working with team-based workflows, Claude uses this resource to:

* Find team IDs
* Understand team composition
* Verify team capabilities

**Example conversation**:

> **You**: "Execute the Infrastructure team to deploy the application"
>
> **Claude**:
>
> 1. Reads `teams://list` resource
> 2. Finds "Infrastructure Team" with ID `team-xyz789`
> 3. Verifies the team has deployment capabilities
> 4. Calls `execute_team` with appropriate parameters

***

### worker-queues\://list

**Description**: All worker queues with status and active workers.

**Includes**:

* Queue ID, name, display name
* Associated environment
* Status (active, paused, etc.)
* Active worker count
* Max workers configuration
* Heartbeat interval
* Last heartbeat timestamp

**Usage**:
For monitoring and queue management:

* Check queue health
* Verify worker availability
* Monitor queue capacity

**Example conversation**:

> **You**: "How many workers are active in production?"
>
> **Claude**:
>
> 1. Reads `worker-queues://list` resource
> 2. Filters queues by production environment
> 3. Sums active workers
> 4. Reports the count

***

### environments\://list

**Description**: All deployment environments with configurations.

**Includes**:

* Environment ID, name, display name
* Description and tags
* Status (active, inactive)
* Created/updated timestamps
* Associated resources

**Usage**:
When creating or executing agents/teams:

* Validate environment IDs
* Understand available environments
* Check environment status

**Example conversation**:

> **You**: "Create an agent for the staging environment"
>
> **Claude**:
>
> 1. Reads `environments://list` resource
> 2. Finds "staging" environment ID
> 3. Calls `create_agent` with environment\_id

***

### projects\://list

**Description**: All projects with metadata and configurations.

**Includes**:

* Project ID, name, key
* Description and visibility
* Status and tags
* Created/updated timestamps
* Associated resources

**Usage**:
For project-based organization:

* Associate agents with projects
* Validate project IDs
* Understand project structure

**Example conversation**:

> **You**: "Add the new agent to the Infrastructure project"
>
> **Claude**:
>
> 1. Reads `projects://list` resource
> 2. Finds "Infrastructure" project ID
> 3. Updates agent with project\_ids

***

### skills\://list

**Description**: All available skills (toolsets) with their configurations.

**Includes**:

* Skill ID, name, type
* Description and documentation
* Enabled status
* Capabilities and tools
* Version information

**Usage**:
When configuring agents and teams:

* Discover available toolsets
* Validate skill IDs
* Understand tool capabilities

**Example conversation**:

> **You**: "Create an agent with kubectl and terraform skills"
>
> **Claude**:
>
> 1. Reads `skills://list` resource
> 2. Finds kubectl skill ID and terraform skill ID
> 3. Creates agent with skill\_ids array

***

### policies\://list

**Description**: All OPA policies for access control.

**Includes**:

* Policy ID, name, type
* Description and tags
* Policy content (OPA/Rego code)
* Enabled status
* Created/updated timestamps

**Usage**:
For security and governance:

* Review access policies
* Validate policy IDs
* Understand authorization rules

**Example conversation**:

> **You**: "What policies are enabled?"
>
> **Claude**:
>
> 1. Reads `policies://list` resource
> 2. Filters by enabled=true
> 3. Lists policy names and descriptions

***

### jobs\://list

**Description**: All scheduled jobs with configurations.

**Includes**:

* Job ID, name, description
* Trigger type (cron, webhook, manual)
* Schedule configuration
* Associated entity (agent/team)
* Enabled status
* Last execution timestamp

**Usage**:
For job management:

* List scheduled tasks
* Validate job IDs
* Monitor job schedules

**Example conversation**:

> **You**: "What jobs are scheduled for tomorrow?"
>
> **Claude**:
>
> 1. Reads `jobs://list` resource
> 2. Parses cron schedules
> 3. Identifies jobs that run tomorrow
> 4. Lists job names and times

***

## How Resources Work

### Resource URIs

Each resource is identified by a URI in the format `<type>://<path>`:

```
agents://list
teams://list
worker-queues://list
environments://list
projects://list
skills://list
policies://list
jobs://list
```

### Resource Access

Resources are read-only and accessed by the AI assistant automatically. You don't need to explicitly request them - Claude reads them as needed when processing your requests.

### Caching

Resources are fetched on-demand from the Kubiya API. The MCP server doesn't cache resource data, ensuring you always get fresh information.

## Resource vs Tools

Understanding when the AI uses resources vs tools:

<Tabs>
  <Tab title="Resources (Read Context)">
    **Used for**:

    * Discovering available entities
    * Validating IDs before tool calls
    * Understanding current state
    * Making informed decisions

    **Examples**:

    * "What agents do I have?" → Read `agents://list`
    * "Show me production environments" → Read `environments://list`
    * "What skills are available?" → Read `skills://list`
  </Tab>

  <Tab title="Tools (Perform Actions)">
    **Used for**:

    * Executing operations
    * Creating/updating/deleting entities
    * Triggering workflows
    * Getting detailed information

    **Examples**:

    * "Execute the DevOps agent" → Call `execute_agent` tool
    * "Create a new environment" → Call `create_environment` tool
    * "Delete the test agent" → Call `delete_agent` tool
  </Tab>
</Tabs>

## Example: Combined Usage

Here's how Claude uses resources and tools together:

<Steps>
  <Step title="Read Resource for Context">
    **You**: "Run the DevOps agent with the production environment"

    **Claude**: Reads `agents://list` and `environments://list` resources to find IDs
  </Step>

  <Step title="Validate Parameters">
    **Claude**: Verifies:

    * DevOps agent exists (found ID: `agent-abc123`)
    * Production environment exists (found ID: `env-prod-456`)
  </Step>

  <Step title="Call Tool">
    **Claude**: Calls `execute_agent` tool:

    ```json theme={null}
    {
      "agent_id": "agent-abc123",
      "prompt": "Check production health",
      "environment_id": "env-prod-456"
    }
    ```
  </Step>

  <Step title="Monitor Execution">
    **Claude**: Calls `stream_execution_to_completion` to monitor progress
  </Step>
</Steps>

## Resource Format

All resources return JSON data. Here's an example of what the `agents://list` resource might return:

```json theme={null}
{
  "agents": [
    {
      "id": "agent-abc123",
      "name": "DevOps Agent",
      "description": "Manages Kubernetes and infrastructure",
      "model": "gpt-4",
      "instructions": "You are a DevOps expert...",
      "skills": [
        {"id": "skill-kubectl", "name": "kubectl"},
        {"id": "skill-helm", "name": "helm"}
      ],
      "environments": [
        {"id": "env-prod", "name": "production"},
        {"id": "env-staging", "name": "staging"}
      ],
      "created_at": "2025-01-15T10:00:00Z",
      "updated_at": "2025-01-20T14:30:00Z"
    },
    {
      "id": "agent-def456",
      "name": "Support Agent",
      "description": "Handles customer support tickets",
      "model": "claude-3-5-sonnet",
      "instructions": "You are a helpful support agent...",
      "skills": [
        {"id": "skill-slack", "name": "slack"},
        {"id": "skill-jira", "name": "jira"}
      ],
      "environments": [
        {"id": "env-prod", "name": "production"}
      ],
      "created_at": "2025-01-10T08:00:00Z",
      "updated_at": "2025-01-18T11:15:00Z"
    }
  ],
  "total": 2
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Let resources work automatically">
    You don't need to explicitly ask Claude to "check resources first." It does this automatically when needed.

    **Good**: "Execute the DevOps agent"

    **Unnecessary**: "First check what agents exist, then execute the DevOps agent"
  </Accordion>

  <Accordion title="Use descriptive names">
    When asking Claude to work with entities, use clear names. Resources help Claude find the right matches.

    **Good**: "Run the DevOps agent"

    **Less clear**: "Run the first agent"
  </Accordion>

  <Accordion title="Trust resource validation">
    If Claude says an entity doesn't exist, it's reading current resource data. The entity may have been deleted or renamed.

    **Response**: Create a new entity or check the dashboard
  </Accordion>

  <Accordion title="Resources are read-only">
    To modify infrastructure, Claude must use tools. Resources only provide context.

    **To change**: Ask Claude to use appropriate tools (create, update, delete)
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Claude says entity not found">
    **Problem**: Claude reads resources but can't find the entity you mentioned.

    **Solutions**:

    1. Check the entity name spelling
    2. Verify the entity exists in the [Kubiya Dashboard](https://app.kubiya.ai)
    3. Try listing entities: "What agents do I have?"
    4. Use the exact name as it appears in the dashboard
  </Accordion>

  <Accordion title="Resource data seems outdated">
    **Problem**: Information appears stale.

    **Solutions**:

    1. Resources are fetched fresh each time - check if changes were saved in the dashboard
    2. Restart Claude Desktop to ensure clean resource fetch
    3. Verify API connectivity with `health_check` tool
  </Accordion>

  <Accordion title="Can't modify resource data">
    **Problem**: Trying to change resource content.

    **Solution**: Resources are read-only. Use tools instead:

    * Create: `create_agent`, `create_team`, etc.
    * Update: `update_agent`, `update_environment`, etc.
    * Delete: `delete_agent`, `delete_policy`, etc.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Tools Reference" icon="wrench" href="/mcp/tools-reference">
    See all available tools that work with these resources
  </Card>

  <Card title="Examples" icon="lightbulb" href="/mcp/examples">
    View practical examples of resources and tools working together
  </Card>

  <Card title="Configuration" icon="gear" href="/mcp/configuration">
    Configure the MCP server
  </Card>

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