# Komodo MCP Server - Migration Guide
Guide for migrating from direct Komodo API usage to the MCP server integration with Claude.
## Table of Contents
1. [Why Migrate?](#why-migrate)
2. [Migration Overview](#migration-overview)
3. [From REST API to MCP](#from-rest-api-to-mcp)
4. [From CLI Scripts to Natural Language](#from-cli-scripts-to-natural-language)
5. [From Custom Integrations](#from-custom-integrations)
6. [Breaking Changes](#breaking-changes)
7. [Migration Checklist](#migration-checklist)
---
## Why Migrate?
### Benefits of MCP Integration
**Before (Direct API)**:
```bash
# Complex curl command
curl -X GET \
-H "X-Komodo-Api-Key: $API_KEY" \
-H "X-Komodo-Timestamp: $(date +%s)" \
-H "X-Komodo-Signature: $(generate_signature)" \
https://komodo.example.com/api/servers?status=running
# Parse JSON response
# Handle errors
# Format output
```
**After (MCP)**:
```
"Show me all running servers"
```
### Key Advantages
1. **Natural Language**: Describe what you want instead of crafting API calls
2. **Automatic Authentication**: No manual signature generation
3. **Error Handling**: Built-in retry logic and error recovery
4. **Context Awareness**: Claude understands relationships between resources
5. **Multi-Step Workflows**: Chain operations naturally
6. **Type Safety**: Automatic parameter validation
---
## Migration Overview
### Phase 1: Setup (1 hour)
1. Install Komodo MCP server
2. Configure credentials
3. Add to Claude
4. Test connection
### Phase 2: Learn (1-2 days)
1. Familiarize with tool naming
2. Try common operations
3. Understand response formats
4. Practice with [examples](./EXAMPLES.md)
### Phase 3: Migrate Scripts (Ongoing)
1. Identify frequently used API calls
2. Replace with Claude commands
3. Update documentation
4. Train team members
### Phase 4: Optimization (Ongoing)
1. Create reusable workflows
2. Integrate with other tools
3. Automate common tasks
4. Monitor and improve
---
## From REST API to MCP
### Server Management
**Before (Direct API)**:
```bash
#!/bin/bash
# List all servers
API_KEY="your-key"
API_SECRET="your-secret"
TIMESTAMP=$(date +%s)
# Generate signature
PAYLOAD="GET/api/servers$TIMESTAMP"
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" | cut -d' ' -f2)
# Make request
curl -X GET \
-H "X-Komodo-Api-Key: $API_KEY" \
-H "X-Komodo-Timestamp: $TIMESTAMP" \
-H "X-Komodo-Signature: $SIGNATURE" \
https://komodo.example.com/api/servers | jq .
```
**After (MCP)**:
```
"Show me all servers"
```
**Or programmatically**:
```typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
const servers = await client.callTool('komodo_read_ListServers', {});
console.log(servers);
```
---
### Deployment Operations
**Before (Direct API)**:
```bash
#!/bin/bash
# Deploy application
DEPLOYMENT_ID="dep_456def"
API_KEY="your-key"
API_SECRET="your-secret"
TIMESTAMP=$(date +%s)
# Create request body
BODY='{"options":{"force":true,"stopBeforeStart":true}}'
# Generate signature
PAYLOAD="POST/api/execute/deploy/$DEPLOYMENT_ID$BODY$TIMESTAMP"
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" | cut -d' ' -f2)
# Make request
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Komodo-Api-Key: $API_KEY" \
-H "X-Komodo-Timestamp: $TIMESTAMP" \
-H "X-Komodo-Signature: $SIGNATURE" \
-d "$BODY" \
https://komodo.example.com/api/execute/deploy/$DEPLOYMENT_ID
# Wait for completion (manual polling required)
while true; do
# Check deployment status
# Parse response
# Sleep
sleep 5
done
```
**After (MCP)**:
```
"Deploy dep_456def and wait for it to complete"
```
Claude automatically:
- Handles authentication
- Triggers deployment
- Monitors progress
- Reports completion
---
### Build Triggering
**Before (Direct API)**:
```python
import hmac
import hashlib
import time
import requests
def trigger_build(build_id, options=None):
api_key = "your-key"
api_secret = "your-secret"
timestamp = str(int(time.time()))
# Prepare request
endpoint = f"/api/execute/build/{build_id}"
method = "POST"
body = json.dumps(options) if options else ""
# Generate signature
payload = f"{method}{endpoint}{body}{timestamp}"
signature = hmac.new(
api_secret.encode(),
payload.encode(),
hashlib.sha256
).hexdigest()
# Make request
headers = {
"X-Komodo-Api-Key": api_key,
"X-Komodo-Timestamp": timestamp,
"X-Komodo-Signature": signature,
"Content-Type": "application/json"
}
response = requests.post(
f"https://komodo.example.com{endpoint}",
headers=headers,
data=body
)
return response.json()
# Usage
result = trigger_build("bld_xyz789", {
"skipCache": True
})
print(result)
```
**After (MCP)**:
```
"Build bld_xyz789 without cache"
```
Or with SDK:
```typescript
const result = await client.callTool('komodo_execute_Build', {
id: 'bld_xyz789',
options: { skipCache: true }
});
```
---
### Monitoring and Alerts
**Before (Direct API)**:
```javascript
// Complex monitoring script
const axios = require('axios');
const crypto = require('crypto');
async function checkAlerts() {
const apiKey = process.env.KOMODO_API_KEY;
const apiSecret = process.env.KOMODO_API_SECRET;
// Get critical alerts
const criticalAlerts = await authenticatedRequest(
'GET',
'/api/alerts?severity=critical&resolved=false'
);
for (const alert of criticalAlerts.items) {
// Get resource details
const resource = await authenticatedRequest(
'GET',
`/api/server/${alert.resource_id}`
);
// Analyze and act
console.log(`Alert: ${alert.title}`);
console.log(`Resource: ${resource.name}`);
console.log(`Metrics:`, alert.metrics);
// Decide action
if (alert.severity === 'critical') {
// Trigger remediation...
}
}
}
async function authenticatedRequest(method, endpoint, body = null) {
// Manual authentication logic...
// Error handling...
// Retry logic...
}
setInterval(checkAlerts, 60000); // Poll every minute
```
**After (MCP)**:
```
"Check for critical alerts and tell me what actions to take"
```
Claude will:
- Fetch critical alerts
- Get resource details
- Analyze the situation
- Recommend actions
- Execute fixes (with approval)
---
## From CLI Scripts to Natural Language
### Common Script Patterns
#### Health Check Script
**Before**:
```bash
#!/bin/bash
# health-check.sh
echo "Checking server health..."
# Get all servers
servers=$(curl -s ... | jq -r '.items[].id')
for server_id in $servers; do
# Get server details
details=$(curl -s ...)
# Parse metrics
cpu=$(echo $details | jq -r '.metrics.cpu_usage')
memory=$(echo $details | jq -r '.metrics.memory_usage')
# Check thresholds
if [ "$cpu" -gt 80 ]; then
echo "WARNING: $server_id CPU at $cpu%"
fi
if [ "$memory" -gt 80 ]; then
echo "WARNING: $server_id memory at $memory%"
fi
done
```
**After**:
```
"Check the health of all servers and warn me about any issues"
```
---
#### Deployment Pipeline
**Before**:
```yaml
# .github/workflows/deploy.yml
name: Deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Trigger Build
run: |
# Complex curl command
BUILD_RESPONSE=$(curl ...)
BUILD_ID=$(echo $BUILD_RESPONSE | jq -r '.job_id')
- name: Wait for Build
run: |
while true; do
STATUS=$(curl ... | jq -r '.status')
if [ "$STATUS" = "success" ]; then
break
fi
sleep 10
done
- name: Deploy to Staging
run: |
# Another curl command
DEPLOY_RESPONSE=$(curl ...)
- name: Run Tests
run: npm test
- name: Deploy to Production
if: success()
run: |
# Final curl command
```
**After**:
```yaml
# .github/workflows/deploy.yml
name: Deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Deploy with Claude
env:
KOMODO_URL: ${{ secrets.KOMODO_URL }}
KOMODO_API_KEY: ${{ secrets.KOMODO_API_KEY }}
KOMODO_API_SECRET: ${{ secrets.KOMODO_API_SECRET }}
run: |
# Use Claude CLI with MCP
claude -e "Build and deploy ${GITHUB_SHA} to staging, run tests, then deploy to production if successful"
```
---
### Cron Jobs
**Before**:
```bash
# /etc/cron.d/komodo-backup
0 2 * * * root /scripts/backup.sh >> /var/log/backup.log 2>&1
# /scripts/backup.sh
#!/bin/bash
# Manual backup script with API calls
# 50+ lines of bash...
```
**After**:
Replace with Komodo procedure:
```
"Create a scheduled procedure to run backups daily at 2 AM"
```
Then configure the procedure in Komodo UI or via MCP.
---
## From Custom Integrations
### Monitoring Dashboards
**Before**:
```typescript
// Custom dashboard polling
import express from 'express';
const app = express();
// Poll Komodo API every minute
setInterval(async () => {
const servers = await fetchServers();
const deployments = await fetchDeployments();
const alerts = await fetchAlerts();
// Update dashboard
updateDashboard({
servers,
deployments,
alerts
});
}, 60000);
async function fetchServers() {
// Manual API authentication
// Request construction
// Error handling
// Retry logic
}
```
**After**:
```typescript
// Use MCP for simplified polling
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
const client = new Client(config, capabilities);
await client.connect(transport);
setInterval(async () => {
// Simple tool calls
const servers = await client.callTool('komodo_read_ListServers', {});
const deployments = await client.callTool('komodo_read_ListDeployments', {});
const alerts = await client.callTool('komodo_read_ListAlerts', { resolved: false });
updateDashboard({ servers, deployments, alerts });
}, 60000);
```
Benefits:
- No manual authentication
- Automatic retry logic
- Type-safe responses
- Simpler error handling
---
### ChatOps Integration
**Before**:
```javascript
// Slack bot with manual API calls
slackBot.on('message', async (message) => {
if (message.text === 'deploy api') {
// Parse command
// Authenticate with Komodo
// Trigger deployment
// Monitor progress
// Report back to Slack
// Handle errors
}
});
```
**After**:
```javascript
// Slack bot with Claude + MCP
slackBot.on('message', async (message) => {
if (message.text.startsWith('komodo ')) {
// Forward to Claude with MCP
const command = message.text.replace('komodo ', '');
const response = await claude.ask(command);
await slackBot.reply(message, response);
}
});
```
Now users can use natural language:
- "komodo deploy api to staging"
- "komodo show production server health"
- "komodo what critical alerts do we have"
---
## Breaking Changes
### Authentication
**Change**: Manual HMAC signing → Automatic
**Before**:
```javascript
// Manual signature generation required
const signature = generateHmacSignature(payload, secret);
headers['X-Komodo-Signature'] = signature;
```
**After**:
```javascript
// Configure once, use everywhere
process.env.KOMODO_API_KEY = 'your-key';
process.env.KOMODO_API_SECRET = 'your-secret';
// MCP handles all authentication
```
**Migration**: Move credentials from application code to environment variables.
---
### Response Format
**Change**: Raw API responses → Structured MCP responses
**Before**:
```json
{
"id": "srv_123",
"name": "production-api",
"status": "running"
}
```
**After**:
```json
{
"data": {
"id": "srv_123",
"name": "production-api",
"status": "running"
},
"status": 200,
"timestamp": "2026-01-26T15:30:00Z"
}
```
**Migration**: Access data via `response.data` instead of directly.
---
### Error Handling
**Change**: HTTP status codes → Structured error objects
**Before**:
```javascript
try {
const response = await axios.get(url);
return response.data;
} catch (error) {
if (error.response.status === 404) {
// Handle not found
}
}
```
**After**:
```javascript
try {
const result = await client.callTool('komodo_read_GetServer', { id });
return result.data;
} catch (error) {
if (error.code === 'NOT_FOUND') {
// Handle not found
}
}
```
**Migration**: Update error handling to use error codes instead of HTTP status.
---
### Pagination
**Change**: Different parameter names
**Before** (Direct API):
```javascript
const params = {
offset: 0,
limit: 50
};
```
**After** (MCP):
```javascript
const params = {
page: 1,
page_size: 50
};
```
**Migration**: Update pagination logic to use `page` and `page_size`.
---
## Migration Checklist
### Pre-Migration
- [ ] Document current API usage patterns
- [ ] Identify frequently used endpoints
- [ ] List custom scripts and integrations
- [ ] Review authentication setup
- [ ] Backup existing scripts
### Setup
- [ ] Install Komodo MCP server
- [ ] Configure environment variables
- [ ] Add to Claude configuration
- [ ] Test connection with diagnostic tool
- [ ] Verify all required tools are available
### Migration
- [ ] Replace simple API calls first
- [ ] Update authentication in all scripts
- [ ] Migrate monitoring scripts
- [ ] Update deployment pipelines
- [ ] Convert cron jobs to procedures
- [ ] Migrate custom integrations
- [ ] Update documentation
### Testing
- [ ] Test common operations
- [ ] Verify error handling
- [ ] Check performance
- [ ] Validate monitoring
- [ ] Test edge cases
- [ ] Load testing (if applicable)
### Post-Migration
- [ ] Update team documentation
- [ ] Train team members
- [ ] Remove old scripts (after verification period)
- [ ] Monitor for issues
- [ ] Collect feedback
- [ ] Optimize workflows
---
## Side-by-Side Comparison
### Server Status Check
| Aspect | Direct API | MCP |
|--------|-----------|-----|
| **Code Length** | ~30 lines | 1 line |
| **Authentication** | Manual signing | Automatic |
| **Error Handling** | Manual | Built-in retry |
| **Parsing** | jq/manual | Automatic |
| **Maintenance** | High | Low |
### Deployment Workflow
| Aspect | Direct API | MCP |
|--------|-----------|-----|
| **Setup Time** | 1-2 hours | 5 minutes |
| **Code Complexity** | High | Low |
| **Progress Monitoring** | Manual polling | Automatic |
| **Error Recovery** | Custom logic | Built-in |
| **Learning Curve** | Steep | Gentle |
---
## Best Practices for Migration
### 1. Start Small
Begin with read-only operations:
```
"Show me all servers"
"Get deployment dep_123 status"
"List all alerts"
```
### 2. Keep Old Scripts Temporarily
Run both in parallel during transition:
```bash
# Old script (backup)
./old-deploy.sh
# New MCP approach
claude -e "Deploy to staging"
```
### 3. Document Equivalents
Create a mapping table:
| Old Script | New Command |
|------------|-------------|
| `./check-servers.sh` | "Check server health" |
| `./deploy-api.sh` | "Deploy API to production" |
| `./backup-db.sh` | "Run database backup procedure" |
### 4. Gradual Rollout
Week 1: Read operations
Week 2: Simple execute operations
Week 3: Complex workflows
Week 4: Full migration
### 5. Monitor and Adjust
Track:
- Success rate
- Error frequency
- Team satisfaction
- Time savings
---
## Support
Need help migrating?
1. Review [Usage Guide](./USAGE.md) for patterns
2. Check [Examples](./EXAMPLES.md) for common scenarios
3. See [Troubleshooting](./TROUBLESHOOTING.md) for issues
4. Open GitHub issue for migration-specific questions
---
## Success Stories
### Example: Deployment Time
**Before**: 15-minute manual process
1. Build locally
2. Test
3. SSH to server
4. Pull code
5. Restart service
6. Check logs
**After**: 2-minute automated process
```
"Build, test, and deploy API v2.5.0 to production"
```
**Result**: 87% time reduction, zero deployment errors in 3 months
---
### Example: Monitoring
**Before**: Custom dashboard polling every minute, 500 lines of code
**After**: Claude + MCP, natural language queries
```
"Show infrastructure health report"
"Alert me if any server exceeds 80% CPU"
```
**Result**: 90% less code, more flexible monitoring
---
## Conclusion
The Komodo MCP server reduces complexity while adding capabilities. The migration investment pays off quickly through:
- Faster operations
- Fewer errors
- Better team collaboration
- Natural language interface
- Reduced maintenance
Start your migration today with our [Quick Start Guide](./USAGE.md#quick-start).
