# Komodo MCP Server - API Reference
Complete reference for all 60 MCP tools with request/response examples.
## Table of Contents
- [Read Module (16 tools)](#read-module)
- [Servers](#servers)
- [Deployments](#deployments)
- [Stacks](#stacks)
- [Builds](#builds)
- [Repositories](#repositories)
- [Procedures](#procedures)
- [Actions](#actions)
- [Alerts](#alerts)
- [Execute Module (9 tools)](#execute-module)
- [Deployment Operations](#deployment-operations)
- [Build Operations](#build-operations)
- [Server Lifecycle](#server-lifecycle)
- [Procedure Operations](#procedure-operations)
- [Action Operations](#action-operations)
- [Repository Operations](#repository-operations)
---
## Read Module
All read operations are idempotent and safe. They don't modify any state on the server.
### Servers
#### komodo_read_ListServers
List all servers with optional filtering and pagination.
**Tool Name**: `komodo_read_ListServers`
**Parameters**:
```typescript
{
page?: number; // Page number (default: 1)
page_size?: number; // Items per page (default: 50, max: 100)
status?: "running" | "stopped" | "pending" | "error";
}
```
**Request Example**:
```json
{
"page": 1,
"page_size": 20,
"status": "running"
}
```
**Response Example**:
```json
{
"items": [
{
"id": "srv_abc123def456",
"name": "production-api",
"host": "192.168.1.100",
"port": 8080,
"status": "running",
"tags": ["production", "api", "critical"],
"region": "us-east-1",
"provider": "aws",
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-01-26T14:20:00Z"
},
{
"id": "srv_xyz789ghi012",
"name": "staging-web",
"host": "192.168.1.101",
"port": 3000,
"status": "running",
"tags": ["staging", "web"],
"region": "us-west-2",
"provider": "aws",
"createdAt": "2026-01-20T08:00:00Z",
"updatedAt": "2026-01-25T16:45:00Z"
}
],
"total": 2,
"page": 1,
"pageSize": 20
}
```
**Error Responses**:
- `400`: Invalid pagination parameters
- `401`: Authentication failed
- `500`: Server error
---
#### komodo_read_GetServer
Get detailed information about a specific server by ID.
**Tool Name**: `komodo_read_GetServer`
**Parameters**:
```typescript
{
id: string; // Required: Server ID
}
```
**Request Example**:
```json
{
"id": "srv_abc123def456"
}
```
**Response Example**:
```json
{
"id": "srv_abc123def456",
"name": "production-api",
"host": "192.168.1.100",
"port": 8080,
"status": "running",
"tags": ["production", "api", "critical"],
"region": "us-east-1",
"provider": "aws",
"config": {
"memory": "4GB",
"cpu": "4 cores",
"disk": "100GB",
"os": "Ubuntu 22.04"
},
"metrics": {
"uptime": "15d 4h 30m",
"cpu_usage": "45%",
"memory_usage": "2.1GB / 4GB",
"disk_usage": "45GB / 100GB",
"network_in": "1.2MB/s",
"network_out": "0.8MB/s"
},
"deployments": ["dep_123", "dep_456"],
"alerts": [],
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-01-26T14:20:00Z"
}
```
**Error Responses**:
- `400`: Missing or invalid ID
- `401`: Authentication failed
- `404`: Server not found
- `500`: Server error
---
### Deployments
#### komodo_read_ListDeployments
List all deployments with optional filtering.
**Tool Name**: `komodo_read_ListDeployments`
**Parameters**:
```typescript
{
page?: number;
page_size?: number;
server_id?: string; // Filter by server
status?: "running" | "stopped" | "deploying" | "failed";
}
```
**Request Example**:
```json
{
"server_id": "srv_abc123def456",
"status": "running"
}
```
**Response Example**:
```json
{
"items": [
{
"id": "dep_456def789ghi",
"name": "api-v2",
"server_id": "srv_abc123def456",
"status": "running",
"image": "myregistry.io/myapp:v2.1.0",
"tag": "v2.1.0",
"ports": ["8080:80", "8443:443"],
"volumes": ["/data:/app/data"],
"env": {
"NODE_ENV": "production",
"DB_HOST": "db.internal",
"REDIS_URL": "redis://cache.internal:6379"
},
"network": "production-net",
"restart_policy": "unless-stopped",
"health_check": {
"enabled": true,
"endpoint": "/health",
"interval": "30s",
"timeout": "10s"
},
"createdAt": "2026-01-20T08:00:00Z",
"updatedAt": "2026-01-26T12:00:00Z",
"lastDeployedAt": "2026-01-26T12:00:00Z"
}
],
"total": 1,
"page": 1,
"pageSize": 50
}
```
---
#### komodo_read_GetDeployment
Get detailed deployment information including logs and metrics.
**Tool Name**: `komodo_read_GetDeployment`
**Parameters**:
```typescript
{
id: string; // Required: Deployment ID
}
```
**Request Example**:
```json
{
"id": "dep_456def789ghi"
}
```
**Response Example**:
```json
{
"id": "dep_456def789ghi",
"name": "api-v2",
"server_id": "srv_abc123def456",
"server_name": "production-api",
"status": "running",
"image": "myregistry.io/myapp:v2.1.0",
"tag": "v2.1.0",
"container_id": "abc123def456",
"ports": ["8080:80", "8443:443"],
"volumes": ["/data:/app/data"],
"env": {
"NODE_ENV": "production",
"DB_HOST": "db.internal"
},
"metrics": {
"cpu_usage": "35%",
"memory_usage": "512MB / 1GB",
"network_in": "500KB/s",
"network_out": "300KB/s",
"uptime": "6d 2h 15m"
},
"health": {
"status": "healthy",
"last_check": "2026-01-26T15:30:00Z",
"checks_passed": 145,
"checks_failed": 0
},
"deployment_history": [
{
"version": "v2.1.0",
"deployed_at": "2026-01-26T12:00:00Z",
"deployed_by": "user_123",
"status": "success",
"duration": "2m 34s"
},
{
"version": "v2.0.0",
"deployed_at": "2026-01-20T08:00:00Z",
"deployed_by": "user_123",
"status": "success",
"duration": "2m 45s"
}
],
"createdAt": "2026-01-20T08:00:00Z",
"updatedAt": "2026-01-26T12:00:00Z"
}
```
---
### Stacks
#### komodo_read_ListStacks
List all Docker Compose stacks.
**Tool Name**: `komodo_read_ListStacks`
**Parameters**:
```typescript
{
page?: number;
page_size?: number;
status?: "active" | "inactive" | "deploying";
}
```
**Request Example**:
```json
{
"status": "active"
}
```
**Response Example**:
```json
{
"items": [
{
"id": "stk_789ghi012jkl",
"name": "monitoring-stack",
"server_id": "srv_abc123def456",
"status": "active",
"services": ["prometheus", "grafana", "alertmanager"],
"service_count": 3,
"running_services": 3,
"compose_file": "docker-compose.monitoring.yml",
"createdAt": "2026-01-10T14:00:00Z",
"updatedAt": "2026-01-26T10:30:00Z"
}
],
"total": 1,
"page": 1,
"pageSize": 50
}
```
---
#### komodo_read_GetStack
Get detailed stack information including all services.
**Tool Name**: `komodo_read_GetStack`
**Parameters**:
```typescript
{
id: string; // Required: Stack ID
}
```
**Request Example**:
```json
{
"id": "stk_789ghi012jkl"
}
```
**Response Example**:
```json
{
"id": "stk_789ghi012jkl",
"name": "monitoring-stack",
"server_id": "srv_abc123def456",
"server_name": "production-api",
"status": "active",
"services": [
{
"name": "prometheus",
"status": "running",
"image": "prom/prometheus:latest",
"ports": ["9090:9090"],
"replicas": 1
},
{
"name": "grafana",
"status": "running",
"image": "grafana/grafana:latest",
"ports": ["3000:3000"],
"replicas": 1
},
{
"name": "alertmanager",
"status": "running",
"image": "prom/alertmanager:latest",
"ports": ["9093:9093"],
"replicas": 1
}
],
"networks": ["monitoring-net"],
"volumes": ["prometheus-data", "grafana-data"],
"compose_content": "version: '3.8'\nservices:\n prometheus:\n ...",
"createdAt": "2026-01-10T14:00:00Z",
"updatedAt": "2026-01-26T10:30:00Z"
}
```
---
### Builds
#### komodo_read_ListBuilds
List all build configurations.
**Tool Name**: `komodo_read_ListBuilds`
**Parameters**:
```typescript
{
page?: number;
page_size?: number;
repo_id?: string;
status?: "pending" | "building" | "success" | "failed";
}
```
**Request Example**:
```json
{
"repo_id": "repo_abc123",
"status": "success"
}
```
**Response Example**:
```json
{
"items": [
{
"id": "bld_xyz789abc012",
"name": "api-build",
"repo_id": "repo_abc123",
"repo_name": "myapp-backend",
"status": "success",
"branch": "main",
"commit": "abc123def456",
"dockerfile": "Dockerfile",
"build_context": ".",
"image_registry": "myregistry.io",
"image_name": "myapp",
"tags": ["latest", "v2.1.0"],
"last_build_at": "2026-01-26T11:00:00Z",
"last_build_duration": "3m 24s",
"createdAt": "2026-01-15T10:00:00Z",
"updatedAt": "2026-01-26T11:03:24Z"
}
],
"total": 1,
"page": 1,
"pageSize": 50
}
```
---
#### komodo_read_GetBuild
Get build configuration and execution history.
**Tool Name**: `komodo_read_GetBuild`
**Parameters**:
```typescript
{
id: string; // Required: Build ID
}
```
**Request Example**:
```json
{
"id": "bld_xyz789abc012"
}
```
**Response Example**:
```json
{
"id": "bld_xyz789abc012",
"name": "api-build",
"repo_id": "repo_abc123",
"repo_name": "myapp-backend",
"status": "success",
"branch": "main",
"commit": "abc123def456",
"dockerfile": "Dockerfile",
"build_context": ".",
"build_args": {
"NODE_VERSION": "20",
"APP_ENV": "production"
},
"image_registry": "myregistry.io",
"image_name": "myapp",
"tags": ["latest", "v2.1.0"],
"cache_enabled": true,
"build_history": [
{
"build_number": 42,
"commit": "abc123def456",
"branch": "main",
"status": "success",
"started_at": "2026-01-26T11:00:00Z",
"completed_at": "2026-01-26T11:03:24Z",
"duration": "3m 24s",
"image_size": "485MB",
"triggered_by": "user_123"
},
{
"build_number": 41,
"commit": "xyz789abc012",
"branch": "main",
"status": "success",
"started_at": "2026-01-25T15:30:00Z",
"completed_at": "2026-01-25T15:33:45Z",
"duration": "3m 45s",
"image_size": "482MB",
"triggered_by": "webhook"
}
],
"createdAt": "2026-01-15T10:00:00Z",
"updatedAt": "2026-01-26T11:03:24Z"
}
```
---
### Repositories
#### komodo_read_ListRepos
List all connected repositories.
**Tool Name**: `komodo_read_ListRepos`
**Parameters**:
```typescript
{
page?: number;
page_size?: number;
provider?: "github" | "gitlab" | "bitbucket" | "other";
}
```
**Request Example**:
```json
{
"provider": "github"
}
```
**Response Example**:
```json
{
"items": [
{
"id": "repo_abc123def456",
"name": "myapp-backend",
"provider": "github",
"url": "https://github.com/myorg/myapp-backend",
"branch": "main",
"status": "connected",
"last_sync": "2026-01-26T12:00:00Z",
"webhook_configured": true,
"builds": ["bld_xyz789"],
"createdAt": "2026-01-10T09:00:00Z",
"updatedAt": "2026-01-26T12:00:00Z"
}
],
"total": 1,
"page": 1,
"pageSize": 50
}
```
---
#### komodo_read_GetRepo
Get repository details including recent commits and build status.
**Tool Name**: `komodo_read_GetRepo`
**Parameters**:
```typescript
{
id: string; // Required: Repository ID
}
```
**Request Example**:
```json
{
"id": "repo_abc123def456"
}
```
**Response Example**:
```json
{
"id": "repo_abc123def456",
"name": "myapp-backend",
"provider": "github",
"url": "https://github.com/myorg/myapp-backend",
"branch": "main",
"status": "connected",
"credentials": {
"type": "ssh_key",
"configured": true
},
"webhook": {
"enabled": true,
"url": "https://komodo.example.com/webhook/repo_abc123def456",
"events": ["push", "pull_request"]
},
"recent_commits": [
{
"sha": "abc123def456",
"message": "feat: add new API endpoint",
"author": "John Doe",
"timestamp": "2026-01-26T11:00:00Z",
"branch": "main"
},
{
"sha": "xyz789abc012",
"message": "fix: resolve database connection issue",
"author": "Jane Smith",
"timestamp": "2026-01-25T15:30:00Z",
"branch": "main"
}
],
"builds": ["bld_xyz789abc012"],
"last_sync": "2026-01-26T12:00:00Z",
"createdAt": "2026-01-10T09:00:00Z",
"updatedAt": "2026-01-26T12:00:00Z"
}
```
---
### Procedures
#### komodo_read_ListProcedures
List all automation procedures.
**Tool Name**: `komodo_read_ListProcedures`
**Parameters**:
```typescript
{
page?: number;
page_size?: number;
trigger?: "manual" | "scheduled" | "webhook";
}
```
**Request Example**:
```json
{
"trigger": "scheduled"
}
```
**Response Example**:
```json
{
"items": [
{
"id": "proc_123abc456def",
"name": "daily-backup",
"description": "Daily database backup procedure",
"trigger": "scheduled",
"schedule": "0 2 * * *",
"enabled": true,
"steps": 5,
"last_execution": {
"status": "success",
"started_at": "2026-01-26T02:00:00Z",
"completed_at": "2026-01-26T02:05:30Z",
"duration": "5m 30s"
},
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-26T02:05:30Z"
}
],
"total": 1,
"page": 1,
"pageSize": 50
}
```
---
#### komodo_read_GetProcedure
Get procedure configuration and execution history.
**Tool Name**: `komodo_read_GetProcedure`
**Parameters**:
```typescript
{
id: string; // Required: Procedure ID
}
```
**Request Example**:
```json
{
"id": "proc_123abc456def"
}
```
**Response Example**:
```json
{
"id": "proc_123abc456def",
"name": "daily-backup",
"description": "Daily database backup procedure",
"trigger": "scheduled",
"schedule": "0 2 * * *",
"enabled": true,
"steps": [
{
"order": 1,
"type": "execute_action",
"action_id": "act_backup_db",
"config": {}
},
{
"order": 2,
"type": "wait",
"duration": "30s"
},
{
"order": 3,
"type": "execute_action",
"action_id": "act_upload_s3",
"config": {
"bucket": "backups"
}
}
],
"variables": {
"BACKUP_PATH": "/data/backups",
"S3_BUCKET": "prod-backups"
},
"execution_history": [
{
"execution_id": "exec_789",
"status": "success",
"started_at": "2026-01-26T02:00:00Z",
"completed_at": "2026-01-26T02:05:30Z",
"duration": "5m 30s",
"steps_completed": 3,
"steps_failed": 0
},
{
"execution_id": "exec_788",
"status": "success",
"started_at": "2026-01-25T02:00:00Z",
"completed_at": "2026-01-25T02:06:15Z",
"duration": "6m 15s",
"steps_completed": 3,
"steps_failed": 0
}
],
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-26T02:05:30Z"
}
```
---
### Actions
#### komodo_read_ListActions
List all configured actions.
**Tool Name**: `komodo_read_ListActions`
**Parameters**:
```typescript
{
page?: number;
page_size?: number;
type?: "script" | "api" | "notification";
enabled?: boolean;
}
```
**Request Example**:
```json
{
"type": "script",
"enabled": true
}
```
**Response Example**:
```json
{
"items": [
{
"id": "act_456def789ghi",
"name": "backup-database",
"type": "script",
"enabled": true,
"script": "/scripts/backup.sh",
"timeout": "300s",
"last_execution": {
"status": "success",
"executed_at": "2026-01-26T02:00:30Z",
"duration": "45s"
},
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-26T02:00:30Z"
}
],
"total": 1,
"page": 1,
"pageSize": 50
}
```
---
#### komodo_read_GetAction
Get action details and execution logs.
**Tool Name**: `komodo_read_GetAction`
**Parameters**:
```typescript
{
id: string; // Required: Action ID
}
```
**Request Example**:
```json
{
"id": "act_456def789ghi"
}
```
**Response Example**:
```json
{
"id": "act_456def789ghi",
"name": "backup-database",
"description": "Backup PostgreSQL database to local disk",
"type": "script",
"enabled": true,
"config": {
"script": "/scripts/backup.sh",
"working_directory": "/opt/komodo",
"timeout": "300s",
"environment": {
"DB_HOST": "localhost",
"DB_NAME": "production",
"BACKUP_DIR": "/data/backups"
}
},
"execution_history": [
{
"execution_id": "exec_action_123",
"status": "success",
"started_at": "2026-01-26T02:00:30Z",
"completed_at": "2026-01-26T02:01:15Z",
"duration": "45s",
"exit_code": 0,
"output": "Backup completed successfully\nFile: backup-2026-01-26.sql.gz\nSize: 2.3GB"
},
{
"execution_id": "exec_action_122",
"status": "success",
"started_at": "2026-01-25T02:00:30Z",
"completed_at": "2026-01-25T02:01:20Z",
"duration": "50s",
"exit_code": 0,
"output": "Backup completed successfully\nFile: backup-2026-01-25.sql.gz\nSize: 2.2GB"
}
],
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-26T02:01:15Z"
}
```
---
### Alerts
#### komodo_read_ListAlerts
List all system alerts with filtering.
**Tool Name**: `komodo_read_ListAlerts`
**Parameters**:
```typescript
{
page?: number;
page_size?: number;
severity?: "info" | "warning" | "error" | "critical";
resolved?: boolean;
resource_type?: string; // e.g., "server", "deployment"
}
```
**Request Example**:
```json
{
"severity": "critical",
"resolved": false
}
```
**Response Example**:
```json
{
"items": [
{
"id": "alt_789ghi012jkl",
"title": "High CPU Usage on production-api",
"severity": "critical",
"resource_type": "server",
"resource_id": "srv_abc123def456",
"resource_name": "production-api",
"message": "CPU usage has exceeded 90% for 15 minutes",
"resolved": false,
"triggered_at": "2026-01-26T15:30:00Z",
"last_updated": "2026-01-26T15:45:00Z",
"metrics": {
"cpu_usage": "95%",
"threshold": "90%",
"duration": "15m"
}
}
],
"total": 1,
"page": 1,
"pageSize": 50
}
```
---
#### komodo_read_GetAlert
Get detailed alert information.
**Tool Name**: `komodo_read_GetAlert`
**Parameters**:
```typescript
{
id: string; // Required: Alert ID
}
```
**Request Example**:
```json
{
"id": "alt_789ghi012jkl"
}
```
**Response Example**:
```json
{
"id": "alt_789ghi012jkl",
"title": "High CPU Usage on production-api",
"severity": "critical",
"resource_type": "server",
"resource_id": "srv_abc123def456",
"resource_name": "production-api",
"message": "CPU usage has exceeded 90% for 15 minutes",
"description": "The production API server has been experiencing sustained high CPU usage. This may impact response times and service availability.",
"resolved": false,
"triggered_at": "2026-01-26T15:30:00Z",
"last_updated": "2026-01-26T15:45:00Z",
"metrics": {
"cpu_usage": "95%",
"threshold": "90%",
"duration": "15m",
"peak": "98%"
},
"timeline": [
{
"timestamp": "2026-01-26T15:30:00Z",
"event": "Alert triggered",
"cpu_usage": "92%"
},
{
"timestamp": "2026-01-26T15:35:00Z",
"event": "CPU usage increased",
"cpu_usage": "95%"
},
{
"timestamp": "2026-01-26T15:40:00Z",
"event": "Peak CPU usage",
"cpu_usage": "98%"
},
{
"timestamp": "2026-01-26T15:45:00Z",
"event": "CPU usage still high",
"cpu_usage": "95%"
}
],
"suggested_actions": [
"Check running processes on the server",
"Review recent deployments",
"Scale horizontally if sustained",
"Investigate database queries"
],
"related_alerts": [],
"notification_sent": true,
"notified_users": ["user_123", "user_456"]
}
```
---
## Execute Module
Execute operations trigger actions and may have side effects. Most operations are asynchronous and return job IDs for tracking.
### Deployment Operations
#### komodo_execute_Deploy
Execute a deployment.
**Tool Name**: `komodo_execute_Deploy`
**Parameters**:
```typescript
{
id: string; // Required: Deployment ID
options?: {
force?: boolean; // Force deploy even if no changes
stopBeforeStart?: boolean; // Stop before starting
skipPull?: boolean; // Skip pulling latest code
};
}
```
**Request Example**:
```json
{
"id": "dep_456def789ghi",
"options": {
"force": false,
"stopBeforeStart": true,
"skipPull": false
}
}
```
**Response Example**:
```json
{
"job_id": "job_deploy_abc123",
"status": "started",
"deployment_id": "dep_456def789ghi",
"deployment_name": "api-v2",
"server_id": "srv_abc123def456",
"started_at": "2026-01-26T15:30:00Z",
"estimated_duration": "2-5 minutes",
"steps": [
"Pulling image",
"Stopping container",
"Creating new container",
"Starting container",
"Health check"
],
"current_step": "Pulling image",
"log_url": "https://komodo.example.com/deployments/dep_456def789ghi/jobs/job_deploy_abc123"
}
```
**Error Responses**:
- `400`: Invalid deployment ID or options
- `401`: Authentication failed
- `404`: Deployment not found
- `409`: Deployment already in progress
- `500`: Server error
---
### Build Operations
#### komodo_execute_Build
Trigger a build process.
**Tool Name**: `komodo_execute_Build`
**Parameters**:
```typescript
{
id: string; // Required: Build ID
options?: {
skipCache?: boolean; // Skip cached layers
skipPull?: boolean; // Skip pulling code
forceBuild?: boolean; // Force rebuild
};
}
```
**Request Example**:
```json
{
"id": "bld_xyz789abc012",
"options": {
"skipCache": true,
"forceBuild": false
}
}
```
**Response Example**:
```json
{
"job_id": "job_build_def456",
"status": "building",
"build_id": "bld_xyz789abc012",
"build_name": "api-build",
"build_number": 43,
"commit": "abc123def456",
"branch": "main",
"started_at": "2026-01-26T15:35:00Z",
"estimated_duration": "3-5 minutes",
"steps": [
"Cloning repository",
"Building image",
"Pushing to registry",
"Cleanup"
],
"current_step": "Cloning repository",
"log_url": "https://komodo.example.com/builds/bld_xyz789abc012/jobs/job_build_def456",
"stream_url": "wss://komodo.example.com/builds/bld_xyz789abc012/jobs/job_build_def456/stream"
}
```
---
### Server Lifecycle
#### komodo_execute_StartServer
Start a server.
**Tool Name**: `komodo_execute_StartServer`
**Parameters**:
```typescript
{
id: string; // Required: Server ID
options?: {
timeout?: number; // Startup timeout in seconds
waitForHealthy?: boolean; // Wait for healthy status
};
}
```
**Request Example**:
```json
{
"id": "srv_abc123def456",
"options": {
"timeout": 120,
"waitForHealthy": true
}
}
```
**Response Example**:
```json
{
"server_id": "srv_abc123def456",
"server_name": "production-api",
"status": "starting",
"started_at": "2026-01-26T15:40:00Z",
"timeout": 120,
"message": "Server startup initiated"
}
```
---
#### komodo_execute_StopServer
Stop a running server.
**Tool Name**: `komodo_execute_StopServer`
**Parameters**:
```typescript
{
id: string; // Required: Server ID
options?: {
timeout?: number; // Shutdown timeout in seconds
force?: boolean; // Force stop (SIGKILL)
removeContainer?: boolean; // Remove container after stop
};
}
```
**Request Example**:
```json
{
"id": "srv_abc123def456",
"options": {
"timeout": 30,
"force": false,
"removeContainer": false
}
}
```
**Response Example**:
```json
{
"server_id": "srv_abc123def456",
"server_name": "production-api",
"status": "stopping",
"started_at": "2026-01-26T15:42:00Z",
"timeout": 30,
"message": "Server shutdown initiated"
}
```
---
#### komodo_execute_RestartServer
Restart a server.
**Tool Name**: `komodo_execute_RestartServer`
**Parameters**:
```typescript
{
id: string; // Required: Server ID
options?: {
timeout?: number; // Restart timeout in seconds
force?: boolean; // Force restart
waitForHealthy?: boolean; // Wait for healthy status
};
}
```
**Request Example**:
```json
{
"id": "srv_abc123def456",
"options": {
"timeout": 120,
"force": false,
"waitForHealthy": true
}
}
```
**Response Example**:
```json
{
"server_id": "srv_abc123def456",
"server_name": "production-api",
"status": "restarting",
"started_at": "2026-01-26T15:44:00Z",
"timeout": 120,
"steps": ["Stopping", "Starting", "Health check"],
"current_step": "Stopping",
"message": "Server restart initiated"
}
```
---
### Procedure Operations
#### komodo_execute_RunProcedure
Execute a procedure.
**Tool Name**: `komodo_execute_RunProcedure`
**Parameters**:
```typescript
{
id: string; // Required: Procedure ID
variables?: Record<string, string>; // Variables to pass
options?: {
async?: boolean; // Run asynchronously
timeout?: number; // Execution timeout in seconds
};
}
```
**Request Example**:
```json
{
"id": "proc_123abc456def",
"variables": {
"ENV": "production",
"BACKUP_TYPE": "full"
},
"options": {
"async": true,
"timeout": 600
}
}
```
**Response Example**:
```json
{
"execution_id": "exec_789ghi012jkl",
"procedure_id": "proc_123abc456def",
"procedure_name": "daily-backup",
"status": "running",
"started_at": "2026-01-26T15:45:00Z",
"timeout": 600,
"variables": {
"ENV": "production",
"BACKUP_TYPE": "full"
},
"steps_total": 5,
"steps_completed": 0,
"current_step": 1,
"current_step_name": "backup-database",
"log_url": "https://komodo.example.com/procedures/proc_123abc456def/executions/exec_789ghi012jkl"
}
```
---
### Action Operations
#### komodo_execute_TriggerAction
Trigger an action.
**Tool Name**: `komodo_execute_TriggerAction`
**Parameters**:
```typescript
{
id: string; // Required: Action ID
payload?: Record<string, unknown>; // Payload data
options?: {
async?: boolean; // Execute asynchronously
retryOnFailure?: boolean; // Retry if fails
};
}
```
**Request Example**:
```json
{
"id": "act_456def789ghi",
"payload": {
"target": "production",
"notification_channel": "slack"
},
"options": {
"async": false,
"retryOnFailure": true
}
}
```
**Response Example**:
```json
{
"execution_id": "exec_action_mno345",
"action_id": "act_456def789ghi",
"action_name": "backup-database",
"status": "success",
"started_at": "2026-01-26T15:46:00Z",
"completed_at": "2026-01-26T15:46:45Z",
"duration": "45s",
"exit_code": 0,
"output": "Backup completed successfully\nFile: backup-2026-01-26-custom.sql.gz\nSize: 2.3GB"
}
```
---
### Repository Operations
#### komodo_execute_PullRepo
Pull latest changes from a repository.
**Tool Name**: `komodo_execute_PullRepo`
**Parameters**:
```typescript
{
id: string; // Required: Repository ID
options?: {
branch?: string; // Specific branch to pull
force?: boolean; // Force pull, discard local changes
submodules?: boolean; // Update submodules
};
}
```
**Request Example**:
```json
{
"id": "repo_abc123def456",
"options": {
"branch": "main",
"force": false,
"submodules": true
}
}
```
**Response Example**:
```json
{
"job_id": "job_pull_pqr678",
"repo_id": "repo_abc123def456",
"repo_name": "myapp-backend",
"status": "pulling",
"branch": "main",
"started_at": "2026-01-26T15:47:00Z",
"message": "Pulling latest changes from main branch"
}
```
---
#### komodo_execute_CloneRepo
Clone a repository.
**Tool Name**: `komodo_execute_CloneRepo`
**Parameters**:
```typescript
{
id: string; // Required: Repository ID
options?: {
branch?: string; // Specific branch to clone
depth?: number; // Shallow clone depth
submodules?: boolean; // Clone submodules
overwrite?: boolean; // Overwrite if exists
};
}
```
**Request Example**:
```json
{
"id": "repo_abc123def456",
"options": {
"branch": "main",
"depth": 1,
"submodules": false,
"overwrite": false
}
}
```
**Response Example**:
```json
{
"job_id": "job_clone_stu901",
"repo_id": "repo_abc123def456",
"repo_name": "myapp-backend",
"status": "cloning",
"branch": "main",
"target_path": "/opt/komodo/repos/myapp-backend",
"started_at": "2026-01-26T15:48:00Z",
"message": "Cloning repository to /opt/komodo/repos/myapp-backend"
}
```
---
## Common Response Fields
### Success Response
All successful tool executions return data in this format:
```json
{
"data": { ... }, // Tool-specific response data
"status": 200, // HTTP status code
"timestamp": "2026-01-26T15:30:00Z"
}
```
### Error Response
All errors follow this format:
```json
{
"error": "Error message",
"code": "ERROR_CODE",
"status": 400,
"timestamp": "2026-01-26T15:30:00Z",
"details": { ... } // Optional: Additional error context
}
```
### Error Codes
| Code | HTTP Status | Description |
|------|-------------|-------------|
| `AUTH_ERROR` | 401 | Authentication failed |
| `FORBIDDEN` | 403 | Insufficient permissions |
| `NOT_FOUND` | 404 | Resource not found |
| `VALIDATION_ERROR` | 400 | Invalid input parameters |
| `CONFLICT` | 409 | Resource conflict (e.g., already running) |
| `NETWORK_ERROR` | - | Network connectivity issue |
| `TIMEOUT_ERROR` | 504 | Request timeout |
| `INTERNAL_ERROR` | 500 | Server error |
---
## Pagination
All list operations support pagination with consistent parameters:
**Parameters**:
- `page`: Page number (default: 1, minimum: 1)
- `page_size`: Items per page (default: 50, maximum: 100)
**Response**:
```json
{
"items": [...],
"total": 150, // Total items across all pages
"page": 1, // Current page
"pageSize": 50, // Items per page
"totalPages": 3 // Total pages
}
```
---
## Rate Limiting
The MCP server respects Komodo API rate limits:
- **Default**: 100 requests per minute
- **Burst**: 200 requests per minute
- **Header**: `X-RateLimit-Remaining` indicates remaining quota
When rate limited:
```json
{
"error": "Rate limit exceeded",
"code": "RATE_LIMIT_ERROR",
"status": 429,
"retry_after": 60
}
```
---
## Async Operations
Long-running operations return job IDs for tracking:
**Initial Response**:
```json
{
"job_id": "job_abc123",
"status": "started",
"log_url": "https://komodo.example.com/jobs/job_abc123"
}
```
**Check Status**:
Use the appropriate Get tool with the resource ID to check job status.
**Job Statuses**:
- `pending`: Queued, not started
- `starting`: Initialization
- `running`: In progress
- `success`: Completed successfully
- `failed`: Failed with error
- `cancelled`: Manually cancelled
---
## Timestamps
All timestamps use ISO 8601 format in UTC:
```
2026-01-26T15:30:00Z
```
---
## Best Practices
1. **Check before Execute**: Always verify resource status before executing operations
2. **Handle Errors**: Implement error handling for all tool calls
3. **Use Pagination**: Don't fetch all items at once for large lists
4. **Monitor Async Jobs**: Check job status for long-running operations
5. **Respect Rate Limits**: Implement backoff strategies if rate limited
6. **Validate Input**: Ensure IDs and parameters are valid before calling tools
7. **Use Filters**: Apply filters to reduce response size and improve performance
