Configuration

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

Environment Variables

Configure the server using environment variables:

Required

CONTROL_PLANE_API_KEY

string

required

Your Kubiya API key (JWT token). Get it from the Kubiya Dashboard → Settings → API Keys.

export CONTROL_PLANE_API_KEY="eyJhbGc..."

Optional

MCP_PROFILE

string

default:"dev"

Environment profile to use: dev, staging, or prod.

export MCP_PROFILE="prod"

dev
staging
prod

Development profile

API URL: http://localhost:8000
Retry attempts: 2
Log level: debug
Timeout: 30s

Staging profile

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

Production profile

API URL: https://control-plane.kubiya.ai
Retry attempts: 3
Log level: warn
Timeout: 60s

CONTROL_PLANE_API_URL

string

Override the API base URL for custom endpoints.

export CONTROL_PLANE_API_URL="https://custom.kubiya.ai"

This overrides the profile’s default API URL. Useful for:

Self-hosted Kubiya instances
Custom domains
Testing against local servers

LOG_LEVEL

string

default:"info"

Logging verbosity: debug, info, warn, or error.

export LOG_LEVEL="debug"

debug
info
warn
error

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

MCP_ALLOWED_TOOLS

string

default:"*"

Tool whitelist pattern. Controls which tools are available.

export MCP_ALLOWED_TOOLS="list_*,get_*,health_check"

Learn more about tool whitelisting →

Profile Configuration Files

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

Custom Profile Example

File: config/custom.json

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

Usage:

export MCP_PROFILE="custom"
kubiya-mcp

Profile Schema

{
  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

All Tools (Default)
Read-Only Mode
Specific Tools
Category-Based
Execute-Only

export MCP_ALLOWED_TOOLS="*"

Allows: All toolsUse case: Full access for trusted environments

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

export MCP_ALLOWED_TOOLS="list_agents,get_agent,execute_agent,stream_execution_to_completion"

Allows: Only the specified toolsUse case: Restricted access for specific workflows

export MCP_ALLOWED_TOOLS="*_agent,*_team,*_execution"

Allows: All agent, team, and execution toolsUse case: Limit to specific resource categories

export MCP_ALLOWED_TOOLS="execute_*,stream_*,get_execution*,list_agents,list_teams"

Allows:

Execute operations
Execution monitoring
Agent/team discovery

Blocks: Create, update, delete operationsUse case: Execution environment without infrastructure changes

Whitelist Examples

# Monitoring dashboard
export MCP_ALLOWED_TOOLS="list_*,get_*,health_check,list_models"

Claude Desktop Configuration

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

Basic Configuration

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

Advanced Configuration

{
  "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": "*"
      }
    }
  }
}

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

Security Best Practices

Use separate API keys

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.

Enable tool whitelisting

Always use tool whitelisting in production:

# Never use "*" in production
export MCP_ALLOWED_TOOLS="list_*,get_*,execute_agent"

Start restrictive and add tools as needed.

Use environment-specific profiles

Configure different profiles for different environments:

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

# Development
export MCP_PROFILE="dev"
export LOG_LEVEL="debug"

# Production
export MCP_PROFILE="prod"
export LOG_LEVEL="warn"

Secure API keys

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

Monitor and audit

Enable logging and monitor usage:

export LOG_LEVEL="info"  # Log all operations

Review logs for:

Unauthorized access attempts
Unusual tool usage patterns
Failed authentication
Rate limiting events

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:

{
  "retryAttempts": 5,
  "retryDelay": 2000  // milliseconds
}

Timeout Settings

Default timeouts by profile:

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

Override in custom profile:

{
  "timeout": 90000  // 90 seconds in milliseconds
}

For long-running executions, use streaming tools (stream_execution_to_completion) instead of increasing timeout values.

Multiple Server Instances

Configure multiple MCP server instances for different use cases:

{
  "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

Development
CI/CD
Production
Monitoring

# 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

# 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

# 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

# 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

Troubleshooting

Configuration validation failed

Error: Configuration validation failed: API key is requiredSolution:

export CONTROL_PLANE_API_KEY="your-key-here"

Verify it’s set:

echo $CONTROL_PLANE_API_KEY

Tool not available

Error: Tool not found: create_agentSolution: Check your tool whitelist:

# Allow the tool
export MCP_ALLOWED_TOOLS="*"
# Or add it specifically
export MCP_ALLOWED_TOOLS="list_*,get_*,create_agent"

Connection timeout

Error: Request timeout after 60000msSolutions:

Check network connectivity
Verify API URL is correct
Use streaming for long operations
Increase timeout in custom profile (not recommended)

Invalid profile

Error: Profile 'xyz' not foundSolutions:

Use existing profile: dev, staging, or prod
Create custom profile file: config/xyz.json
Verify profile file syntax

Next Steps

Tools Reference

See all available tools

Resources

Learn about context injection

Examples

See configuration examples in action

Quick Start

Get started with Claude Desktop

Getting Started

Reference

Guides

Environment Variables

Required

Optional

Profile Configuration Files

Custom Profile Example

Profile Schema

Tool Whitelisting

Patterns

Whitelist Examples

Claude Desktop Configuration

Basic Configuration

Advanced Configuration

Security Best Practices

Connection Settings

Retry Configuration

Timeout Settings

Multiple Server Instances

Environment-Specific Examples

Troubleshooting

Next Steps

Tools Reference

Resources

Examples

Quick Start

Getting Started

Reference

Guides

​Environment Variables

​Required

​Optional

​Profile Configuration Files

​Custom Profile Example

​Profile Schema

​Tool Whitelisting

​Patterns

​Whitelist Examples

​Claude Desktop Configuration

​Basic Configuration

​Advanced Configuration

​Security Best Practices

​Connection Settings

​Retry Configuration

​Timeout Settings

​Multiple Server Instances

​Environment-Specific Examples

​Troubleshooting

​Next Steps

Tools Reference

Resources

Examples

Quick Start

Environment Variables

Required

Optional

Profile Configuration Files

Custom Profile Example

Profile Schema

Tool Whitelisting

Patterns

Whitelist Examples

Claude Desktop Configuration

Basic Configuration

Advanced Configuration

Security Best Practices

Connection Settings

Retry Configuration

Timeout Settings

Multiple Server Instances

Environment-Specific Examples

Troubleshooting

Next Steps