​
MCP Authentication

The Kubiya MCP server supports multiple authentication methods to secure your tools and protect API access.

​
Authentication Methods

​
1. API Key Authentication (Default)

The simplest and most common approach - use your Kubiya API key: 
# Set your API key
export KUBIYA_API_KEY="your-kubiya-api-key"

# Start the MCP server
kubiya mcp serve

​
Configuration File

Add to your MCP server configuration (~/.kubiya/mcp-server.json): 
{
  "api_key": "your-kubiya-api-key",
  "enable_runners": true,
  "allow_platform_apis": false
}

​
Claude Desktop Configuration

{
  "mcpServers": {
    "kubiya": {
      "command": "kubiya",
      "args": ["mcp", "serve"],
      "env": {
        "KUBIYA_API_KEY": "your-kubiya-api-key"
      }
    }
  }
}

​
2. Session-Based Authentication

For production environments, enable session management: 
# Start with session management
kubiya mcp serve --production --require-auth --session-timeout 3600
This enables:
  • User session management
  • Session timeout (default: 30 minutes)
  • Authentication middleware
  • Access logging

​
3. Token-Based Authentication

Use temporary tokens for enhanced security: 
# Generate a temporary token
kubiya auth token generate --expires 1h

# Use the token
export KUBIYA_AUTH_TOKEN="your-temporary-token"
kubiya mcp serve --require-auth

​
Configuration Options

​
Basic Configuration

{
  "enable_runners": true,
  "allow_platform_apis": false,
  "enable_opa_policies": false,
  "verbose_logging": false,
  "require_auth": false,
  "session_timeout": 1800
}

​
Enterprise Configuration

{
  "enable_runners": true,
  "allow_platform_apis": true,
  "enable_opa_policies": true,
  "verbose_logging": true,
  "require_auth": true,
  "session_timeout": 3600,
  "whitelisted_tools": [
    {
      "name": "kubectl",
      "description": "Kubernetes CLI tool",
      "type": "docker",
      "image": "kubiya/kubectl-light:latest"
    }
  ]
}

​
Security Features

​
1. OPA Policy Enforcement

Enable Open Policy Agent (OPA) for policy-based access control: 
# Enable OPA policies
kubiya mcp serve --enable-opa-policies

# Or via environment variable
export KUBIYA_OPA_ENFORCE=true
kubiya mcp serve

​
2. Tool Whitelisting

Restrict which tools can be executed: 
{
  "whitelisted_tools": [
    {
      "name": "kubectl",
      "description": "Kubernetes commands",
      "type": "docker",
      "image": "kubiya/kubectl-light:latest"
    },
    {
      "name": "terraform",
      "description": "Infrastructure as code",
      "type": "docker",
      "image": "hashicorp/terraform:latest"
    }
  ]
}

​
3. Runner Restrictions

Control which runners can be used: 
# Disable runners entirely
kubiya mcp serve --disable-runners

# Or limit to specific runners
kubiya mcp serve --allowed-runners runner1,runner2

​
API Key Management

​
Creating API Keys

  1. Go to Kubiya Settings
  2. Navigate to “API Keys”
  3. Click “Create New Key”
  4. Set appropriate permissions
  5. Copy the key securely

​
Key Rotation

# Create a new key
kubiya auth key create --name "mcp-server-key" --expires 30d

# Update your configuration
export KUBIYA_API_KEY="new-api-key"

# Revoke old key
kubiya auth key revoke old-key-id

​
Key Permissions

Configure API key permissions:
PermissionDescription
tools:executeExecute tools and workflows
tools:listList available tools
runners:readView runner status
runners:manageCreate/delete runners
agents:readView agents
agents:manageCreate/modify agents

​
Access Control

​
Role-Based Access

Define roles for different users: 
{
  "roles": {
    "developer": {
      "permissions": ["tools:execute", "tools:list", "runners:read"],
      "allowed_tools": ["kubectl", "docker", "git"]
    },
    "admin": {
      "permissions": ["*"],
      "allowed_tools": ["*"]
    }
  }
}

​
IP Whitelisting

Restrict access by IP address: 
{
  "allowed_ips": [
    "192.168.1.0/24",
    "10.0.0.0/8"
  ]
}

​
Monitoring and Logging

​
Authentication Logs

Enable detailed authentication logging: 
# Enable verbose logging
kubiya mcp serve --verbose

# Or via environment
export LOG_LEVEL=DEBUG
kubiya mcp serve

​
Audit Trail

All authenticated actions are logged: 
{
  "timestamp": "2024-01-15T10:30:00Z",
  "user_id": "user123",
  "action": "execute_tool",
  "tool_name": "kubectl",
  "parameters": {"command": "get pods"},
  "result": "success"
}

​
Security Best Practices

​
1. Environment Security

  • Use environment variables for sensitive data
  • Never commit API keys to version control
  • Rotate keys regularly
  • Use separate keys for different environments

​
2. Network Security

  • Use HTTPS/TLS for all communications
  • Implement IP whitelisting
  • Use VPN for remote access
  • Monitor network traffic

​
3. Access Control

  • Implement least privilege principle
  • Use role-based access control
  • Enable OPA policies for fine-grained control
  • Regular access reviews

​
4. Monitoring

  • Enable comprehensive logging
  • Set up alerts for failed authentications
  • Monitor API key usage
  • Track tool execution patterns

​
Troubleshooting

​
Common Issues

​
”Authentication failed” Error

Check:
  1. API key is valid and not expired
  2. Environment variable is set correctly
  3. Key has required permissions
  4. Network connectivity to Kubiya API

​
”Insufficient permissions” Error

Verify:
  1. API key has necessary permissions
  2. Tool is whitelisted (if using whitelist)
  3. OPA policies allow the action
  4. User role includes required permissions

​
”Session expired” Error

Solutions:
  1. Extend session timeout
  2. Re-authenticate with fresh token
  3. Check system clock synchronization
  4. Verify token expiration time

​
Debug Mode

Enable debug mode for detailed troubleshooting: 
# Start with debug logging
kubiya --debug mcp serve

# Or set environment variable
export DEBUG=true
kubiya mcp serve

​
Migration Guide

​
From Basic to Secure Setup

  1. Enable Authentication: 
    kubiya mcp serve --require-auth
  2. Add OPA Policies: 
    kubiya mcp serve --enable-opa-policies
  3. Configure Whitelisting: 
    {
  "whitelisted_tools": ["kubectl", "terraform"]
}
  4. Test Thoroughly:
    • Verify all tools work
    • Test authentication flows
    • Validate policy enforcement

​
Next Steps