MCP Protocol Implementation
Kubiya implements the Model Context Protocol (MCP) specification to enable seamless integration with AI assistants and tools.Protocol Version
Kubiya MCP server implements MCP Protocol Version 2024-11-05.Transport Layer
Standard I/O Transport
The primary transport method uses standard input/output streams:Server Capabilities
The Kubiya MCP server advertises the following capabilities:Message Types
Initialize
Client initialization with server capability negotiation.Tools
- tools/list: List available tools
- tools/call: Execute specific tools
Resources
- resources/list: List available resources
- resources/read: Read resource content
- resources/subscribe: Subscribe to resource changes
Prompts
- prompts/list: List available prompt templates
- prompts/get: Retrieve specific prompts
Tool Execution Flow
Error Handling
Standard Error Codes
| Code | Description | 
|---|---|
| -32700 | Parse Error | 
| -32600 | Invalid Request | 
| -32601 | Method Not Found | 
| -32602 | Invalid Parameters | 
| -32603 | Internal Error | 
Kubiya-Specific Error Codes
| Code | Description | 
|---|---|
| 1001 | Authentication Failed | 
| 1002 | Policy Violation | 
| 1003 | Runner Unavailable | 
| 1004 | Tool Not Found | 
| 1005 | Execution Timeout | 
Security Implementation
Authentication
- API key validation on every request
- User context propagation to execution environment
Authorization
- OPA policy evaluation before tool execution
- Runner-specific permission checks
Audit Logging
- Complete request/response logging
- User attribution for all actions
- Execution telemetry and metrics
Configuration
Environment Variables
| Variable | Purpose | Default | 
|---|---|---|
| KUBIYA_API_KEY | Authentication | Required | 
| KUBIYA_API_URL | API endpoint | https://api.kubiya.ai | 
| KUBIYA_MCP_LOG_LEVEL | Logging verbosity | info | 
| KUBIYA_MCP_TIMEOUT | Request timeout | 300s | 
Server Options
Client Integration Examples
Python Client
TypeScript Client
Performance Considerations
Connection Pooling
- MCP server maintains persistent connections
- Automatic reconnection on network failures
Streaming Support
- Real-time output streaming for long-running tools
- Progress updates during workflow execution
Caching
- Tool definitions cached for performance
- Runner health status cached for 30 seconds
Monitoring and Observability
Metrics
- Request count and latency
- Tool execution success/failure rates
- Runner utilization statistics
Logging
- Structured JSON logging
- Correlation IDs for request tracing
- Performance metrics collection
Health Checks
- Server health endpoint
- Dependency health monitoring
- Graceful degradation on failures