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:

kubiya mcp serve

Server Capabilities

The Kubiya MCP server advertises the following capabilities:

{
  "capabilities": {
    "tools": {
      "listChanged": true
    },
    "resources": {
      "subscribe": true,
      "listChanged": true
    },
    "prompts": {
      "listChanged": true
    },
    "logging": {
      "level": "info"
    }
  },
  "protocolVersion": "2024-11-05",
  "serverInfo": {
    "name": "kubiya-mcp-server",
    "version": "1.0.0"
  }
}

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

CodeDescription
-32700Parse Error
-32600Invalid Request
-32601Method Not Found
-32602Invalid Parameters
-32603Internal Error

Kubiya-Specific Error Codes

CodeDescription
1001Authentication Failed
1002Policy Violation
1003Runner Unavailable
1004Tool Not Found
1005Execution 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

VariablePurposeDefault
KUBIYA_API_KEYAuthenticationRequired
KUBIYA_API_URLAPI endpointhttps://api.kubiya.ai
KUBIYA_MCP_LOG_LEVELLogging verbosityinfo
KUBIYA_MCP_TIMEOUTRequest timeout300s

Server Options

# Basic server
kubiya mcp serve

# With debug logging
kubiya mcp serve --log-level debug

# With custom configuration
kubiya mcp serve --config ~/.kubiya/mcp-config.json

Client Integration Examples

Python Client

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import StdioServerTransport

async def connect_to_kubiya():
    server_params = StdioServerParameters(
        command="kubiya",
        args=["mcp", "serve"],
        env={"KUBIYA_API_KEY": "kb-your-key"}
    )
    
    async with StdioServerTransport(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # List tools
            tools_result = await session.list_tools()
            print(f"Available tools: {len(tools_result.tools)}")
            
            # Execute tool
            result = await session.call_tool(
                "execute_tool",
                {"tool_name": "echo", "args": {"message": "Hello"}}
            )
            print(result.content)

TypeScript Client

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

async function connectToKubiya() {
  const transport = new StdioClientTransport({
    command: "kubiya",
    args: ["mcp", "serve"],
    env: { KUBIYA_API_KEY: "kb-your-key" }
  });

  const client = new Client({
    name: "kubiya-client",
    version: "1.0.0"
  }, {
    capabilities: {
      tools: {}
    }
  });

  await client.connect(transport);
  
  // List and call tools
  const tools = await client.listTools();
  console.log(`Available tools: ${tools.tools.length}`);
}

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