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

# Configuration

> Configure environments, security, and advanced options

The Kubiya MCP Server supports flexible configuration through environment variables and profile files.

## Environment Variables

Configure the server using environment variables:

### Required

<ParamField path="CONTROL_PLANE_API_KEY" type="string" required>
  Your Kubiya API key (JWT token). Get it from the [Kubiya Dashboard](https://app.kubiya.ai) → Settings → API Keys.

  ```bash theme={null}
  export CONTROL_PLANE_API_KEY="eyJhbGc..."
  ```
</ParamField>

### Optional

<ParamField path="MCP_PROFILE" type="string" default="dev">
  Environment profile to use: `dev`, `staging`, or `prod`.

  ```bash theme={null}
  export MCP_PROFILE="prod"
  ```

  <Tabs>
    <Tab title="dev">
      **Development profile**

      * API URL: `http://localhost:8000`
      * Retry attempts: 2
      * Log level: debug
      * Timeout: 30s
    </Tab>

    <Tab title="staging">
      **Staging profile**

      * API URL: `https://staging-control-plane.kubiya.ai`
      * Retry attempts: 3
      * Log level: info
      * Timeout: 60s
    </Tab>

    <Tab title="prod">
      **Production profile**

      * API URL: `https://control-plane.kubiya.ai`
      * Retry attempts: 3
      * Log level: warn
      * Timeout: 60s
    </Tab>
  </Tabs>
</ParamField>

<ParamField path="CONTROL_PLANE_API_URL" type="string">
  Override the API base URL for custom endpoints.

  ```bash theme={null}
  export CONTROL_PLANE_API_URL="https://custom.kubiya.ai"
  ```

  <Note>
    This overrides the profile's default API URL. Useful for:

    * Self-hosted Kubiya instances
    * Custom domains
    * Testing against local servers
  </Note>
</ParamField>

<ParamField path="LOG_LEVEL" type="string" default="info">
  Logging verbosity: `debug`, `info`, `warn`, or `error`.

  ```bash theme={null}
  export LOG_LEVEL="debug"
  ```

  <Tabs>
    <Tab title="debug">
      **Most verbose** - Shows all requests, responses, and internal operations. Use for troubleshooting.

      Output includes:

      * API requests and responses
      * Tool execution details
      * Resource fetching operations
      * Error stack traces
    </Tab>

    <Tab title="info">
      **Normal** - Shows important operations and status updates.

      Output includes:

      * Server startup
      * Tool registrations
      * Request processing
      * Major operations
    </Tab>

    <Tab title="warn">
      **Warnings only** - Shows potential issues and warnings.

      Output includes:

      * Authentication warnings
      * Rate limiting
      * Deprecated features
      * Non-fatal errors
    </Tab>

    <Tab title="error">
      **Errors only** - Shows only errors and failures.

      Output includes:

      * API errors
      * Connection failures
      * Tool execution errors
      * Fatal errors
    </Tab>
  </Tabs>
</ParamField>

<ParamField path="MCP_ALLOWED_TOOLS" type="string" default="*">
  Tool whitelist pattern. Controls which tools are available.

  ```bash theme={null}
  export MCP_ALLOWED_TOOLS="list_*,get_*,health_check"
  ```

  [Learn more about tool whitelisting →](#tool-whitelisting)
</ParamField>

## Profile Configuration Files

Create custom profile configurations in `config/<profile-name>.json`:

### Custom Profile Example

**File**: `config/custom.json`

```json theme={null}
{
  "apiBaseUrl": "https://custom.kubiya.ai",
  "logLevel": "info",
  "retryAttempts": 5,
  "retryDelay": 2000,
  "timeout": 60000,
  "allowedTools": ["list_*", "get_*", "execute_*"]
}
```

**Usage**:

```bash theme={null}
export MCP_PROFILE="custom"
kubiya-mcp
```

### Profile Schema

```typescript theme={null}
{
  apiBaseUrl: string;      // API endpoint URL
  logLevel: string;        // debug | info | warn | error
  retryAttempts: number;   // Number of retry attempts
  retryDelay: number;      // Delay between retries (ms)
  timeout: number;         // Request timeout (ms)
  allowedTools: string[];  // Tool whitelist patterns
}
```

## Tool Whitelisting

Control which tools are available to AI assistants using the `MCP_ALLOWED_TOOLS` environment variable.

### Patterns

<Tabs>
  <Tab title="All Tools (Default)">
    ```bash theme={null}
    export MCP_ALLOWED_TOOLS="*"
    ```

    **Allows**: All tools

    **Use case**: Full access for trusted environments
  </Tab>

  <Tab title="Read-Only Mode">
    ```bash theme={null}
    export MCP_ALLOWED_TOOLS="list_*,get_*,health_check"
    ```

    **Allows**:

    * All `list_*` tools (list\_agents, list\_teams, etc.)
    * All `get_*` tools (get\_agent, get\_execution, etc.)
    * health\_check tool

    **Blocks**:

    * Create operations (create\_agent, create\_team, etc.)
    * Update operations (update\_*, delete\_*)
    * Execute operations (execute\_agent, execute\_team)

    **Use case**: Monitoring and reporting without modifications
  </Tab>

  <Tab title="Specific Tools">
    ```bash theme={null}
    export MCP_ALLOWED_TOOLS="list_agents,get_agent,execute_agent,stream_execution_to_completion"
    ```

    **Allows**: Only the specified tools

    **Use case**: Restricted access for specific workflows
  </Tab>

  <Tab title="Category-Based">
    ```bash theme={null}
    export MCP_ALLOWED_TOOLS="*_agent,*_team,*_execution"
    ```

    **Allows**: All agent, team, and execution tools

    **Use case**: Limit to specific resource categories
  </Tab>

  <Tab title="Execute-Only">
    ```bash theme={null}
    export MCP_ALLOWED_TOOLS="execute_*,stream_*,get_execution*,list_agents,list_teams"
    ```

    **Allows**:

    * Execute operations
    * Execution monitoring
    * Agent/team discovery

    **Blocks**: Create, update, delete operations

    **Use case**: Execution environment without infrastructure changes
  </Tab>
</Tabs>

### Whitelist Examples

<CodeGroup>
  ```bash Production Read-Only theme={null}
  # Monitoring dashboard
  export MCP_ALLOWED_TOOLS="list_*,get_*,health_check,list_models"
  ```

  ```bash Agent Execution Only theme={null}
  # Execute agents without creating/modifying
  export MCP_ALLOWED_TOOLS="list_agents,get_agent,execute_agent,list_executions,get_execution,stream_*"
  ```

  ```bash Full Infrastructure Management theme={null}
  # Create, update, delete everything
  export MCP_ALLOWED_TOOLS="*"
  ```

  ```bash Development Safe Mode theme={null}
  # Everything except delete operations
  export MCP_ALLOWED_TOOLS="list_*,get_*,create_*,update_*,execute_*,stream_*,trigger_*"
  ```
</CodeGroup>

## Claude Desktop Configuration

Configure the MCP server in Claude Desktop's config file:

### Basic Configuration

<CodeGroup>
  ```json macOS theme={null}
  {
    "mcpServers": {
      "kubiya": {
        "command": "npx",
        "args": ["@kubiya/control-plane-mcp-server"],
        "env": {
          "CONTROL_PLANE_API_KEY": "your-jwt-token",
          "MCP_PROFILE": "prod"
        }
      }
    }
  }
  ```

  ```json Windows theme={null}
  {
    "mcpServers": {
      "kubiya": {
        "command": "npx",
        "args": ["@kubiya/control-plane-mcp-server"],
        "env": {
          "CONTROL_PLANE_API_KEY": "your-jwt-token",
          "MCP_PROFILE": "prod"
        }
      }
    }
  }
  ```

  ```json Linux theme={null}
  {
    "mcpServers": {
      "kubiya": {
        "command": "npx",
        "args": ["@kubiya/control-plane-mcp-server"],
        "env": {
          "CONTROL_PLANE_API_KEY": "your-jwt-token",
          "MCP_PROFILE": "prod"
        }
      }
    }
  }
  ```
</CodeGroup>

### Advanced Configuration

```json theme={null}
{
  "mcpServers": {
    "kubiya-readonly": {
      "command": "npx",
      "args": ["@kubiya/control-plane-mcp-server"],
      "env": {
        "CONTROL_PLANE_API_KEY": "your-jwt-token",
        "MCP_PROFILE": "prod",
        "LOG_LEVEL": "info",
        "MCP_ALLOWED_TOOLS": "list_*,get_*,health_check"
      }
    },
    "kubiya-full": {
      "command": "npx",
      "args": ["@kubiya/control-plane-mcp-server"],
      "env": {
        "CONTROL_PLANE_API_KEY": "your-admin-jwt-token",
        "MCP_PROFILE": "prod",
        "LOG_LEVEL": "warn",
        "MCP_ALLOWED_TOOLS": "*"
      }
    }
  }
}
```

<Note>
  You can configure multiple MCP server instances with different permissions. Claude Desktop will show both in the MCP servers list.
</Note>

## Security Best Practices

<AccordionGroup>
  <Accordion title="Use separate API keys" icon="key">
    Create different API keys for different purposes:

    * **Development**: Full access for testing
    * **Production read-only**: Limited to list/get operations
    * **CI/CD**: Execute and monitor only
    * **Admin**: Full access for infrastructure changes

    Rotate keys regularly and revoke unused keys.
  </Accordion>

  <Accordion title="Enable tool whitelisting" icon="shield">
    Always use tool whitelisting in production:

    ```bash theme={null}
    # Never use "*" in production
    export MCP_ALLOWED_TOOLS="list_*,get_*,execute_agent"
    ```

    Start restrictive and add tools as needed.
  </Accordion>

  <Accordion title="Use environment-specific profiles" icon="server">
    Configure different profiles for different environments:

    * **dev**: Local testing with debug logging
    * **staging**: Pre-production testing
    * **prod**: Production with minimal logging

    ```bash theme={null}
    # Development
    export MCP_PROFILE="dev"
    export LOG_LEVEL="debug"

    # Production
    export MCP_PROFILE="prod"
    export LOG_LEVEL="warn"
    ```
  </Accordion>

  <Accordion title="Secure API keys" icon="lock">
    **Never**:

    * Commit API keys to version control
    * Share keys via email or chat
    * Use production keys in development
    * Log API keys in debug output

    **Always**:

    * Store keys in secure secret management (Vault, AWS Secrets Manager, etc.)
    * Use environment variables
    * Rotate keys regularly
    * Audit key usage
  </Accordion>

  <Accordion title="Monitor and audit" icon="chart-line">
    Enable logging and monitor usage:

    ```bash theme={null}
    export LOG_LEVEL="info"  # Log all operations
    ```

    Review logs for:

    * Unauthorized access attempts
    * Unusual tool usage patterns
    * Failed authentication
    * Rate limiting events
  </Accordion>
</AccordionGroup>

## Connection Settings

### Retry Configuration

The MCP server automatically retries failed requests with exponential backoff:

* **Development**: 2 retry attempts
* **Staging**: 3 retry attempts
* **Production**: 3 retry attempts

Override in custom profile:

```json theme={null}
{
  "retryAttempts": 5,
  "retryDelay": 2000  // milliseconds
}
```

### Timeout Settings

Default timeouts by profile:

* **Development**: 30 seconds
* **Staging**: 60 seconds
* **Production**: 60 seconds

Override in custom profile:

```json theme={null}
{
  "timeout": 90000  // 90 seconds in milliseconds
}
```

<Warning>
  For long-running executions, use streaming tools (`stream_execution_to_completion`) instead of increasing timeout values.
</Warning>

## Multiple Server Instances

Configure multiple MCP server instances for different use cases:

```json theme={null}
{
  "mcpServers": {
    "kubiya-monitoring": {
      "command": "npx",
      "args": ["@kubiya/control-plane-mcp-server"],
      "env": {
        "CONTROL_PLANE_API_KEY": "monitoring-key",
        "MCP_PROFILE": "prod",
        "MCP_ALLOWED_TOOLS": "list_*,get_*,health_check"
      }
    },
    "kubiya-operations": {
      "command": "npx",
      "args": ["@kubiya/control-plane-mcp-server"],
      "env": {
        "CONTROL_PLANE_API_KEY": "operations-key",
        "MCP_PROFILE": "prod",
        "MCP_ALLOWED_TOOLS": "execute_*,stream_*,get_execution*"
      }
    },
    "kubiya-admin": {
      "command": "npx",
      "args": ["@kubiya/control-plane-mcp-server"],
      "env": {
        "CONTROL_PLANE_API_KEY": "admin-key",
        "MCP_PROFILE": "prod",
        "MCP_ALLOWED_TOOLS": "*"
      }
    }
  }
}
```

## Environment-Specific Examples

<Tabs>
  <Tab title="Development">
    ```bash theme={null}
    # Development environment
    export CONTROL_PLANE_API_KEY="dev-key"
    export MCP_PROFILE="dev"
    export LOG_LEVEL="debug"
    export MCP_ALLOWED_TOOLS="*"
    export CONTROL_PLANE_API_URL="http://localhost:8000"

    kubiya-mcp
    ```
  </Tab>

  <Tab title="CI/CD">
    ```bash theme={null}
    # CI/CD pipeline
    export CONTROL_PLANE_API_KEY="${CI_KUBIYA_KEY}"
    export MCP_PROFILE="prod"
    export LOG_LEVEL="info"
    export MCP_ALLOWED_TOOLS="execute_agent,stream_execution_to_completion"

    kubiya-mcp
    ```
  </Tab>

  <Tab title="Production">
    ```bash theme={null}
    # Production environment
    export CONTROL_PLANE_API_KEY="${KUBIYA_PROD_KEY}"
    export MCP_PROFILE="prod"
    export LOG_LEVEL="warn"
    export MCP_ALLOWED_TOOLS="list_*,get_*,execute_agent"

    kubiya-mcp
    ```
  </Tab>

  <Tab title="Monitoring">
    ```bash theme={null}
    # Monitoring dashboard
    export CONTROL_PLANE_API_KEY="${KUBIYA_READONLY_KEY}"
    export MCP_PROFILE="prod"
    export LOG_LEVEL="error"
    export MCP_ALLOWED_TOOLS="list_*,get_*,health_check"

    kubiya-mcp
    ```
  </Tab>
</Tabs>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Configuration validation failed">
    **Error**: `Configuration validation failed: API key is required`

    **Solution**:

    ```bash theme={null}
    export CONTROL_PLANE_API_KEY="your-key-here"
    ```

    Verify it's set:

    ```bash theme={null}
    echo $CONTROL_PLANE_API_KEY
    ```
  </Accordion>

  <Accordion title="Tool not available">
    **Error**: `Tool not found: create_agent`

    **Solution**: Check your tool whitelist:

    ```bash theme={null}
    # Allow the tool
    export MCP_ALLOWED_TOOLS="*"
    # Or add it specifically
    export MCP_ALLOWED_TOOLS="list_*,get_*,create_agent"
    ```
  </Accordion>

  <Accordion title="Connection timeout">
    **Error**: `Request timeout after 60000ms`

    **Solutions**:

    1. Check network connectivity
    2. Verify API URL is correct
    3. Use streaming for long operations
    4. Increase timeout in custom profile (not recommended)
  </Accordion>

  <Accordion title="Invalid profile">
    **Error**: `Profile 'xyz' not found`

    **Solutions**:

    1. Use existing profile: `dev`, `staging`, or `prod`
    2. Create custom profile file: `config/xyz.json`
    3. Verify profile file syntax
  </Accordion>
</AccordionGroup>

## Next Steps

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

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

  <Card title="Examples" icon="lightbulb" href="/mcp/examples">
    See configuration examples in action
  </Card>

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