​

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:

​

Environment Variable (Recommended)

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

​

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:

   Copy

   kubiya mcp serve --require-auth
   

2. Add OPA Policies:

   Copy

   kubiya mcp serve --enable-opa-policies
   

3. Configure Whitelisting:

   Copy

   {
     "whitelisted_tools": ["kubectl", "terraform"]
   }
   

4. Test Thoroughly:

   • Verify all tools work
   • Test authentication flows
   • Validate policy enforcement

​

Next Steps

• Configure OPA Policies
• Set up Monitoring
• Explore Tools Reference