# Komodo MCP Server - Environment Configuration
This document describes the environment variables required to run the Komodo MCP server.
## Required Environment Variables
### Authentication
| Variable | Description | Required | Example |
|----------|-------------|----------|---------|
| `KOMODO_URL` | Base URL of the Komodo API server | Yes | `https://komodo.example.com` |
| `KOMODO_API_KEY` | API key for authentication | Yes | `km_key_abc123...` |
| `KOMODO_API_SECRET` | API secret for authentication | Yes | `km_secret_xyz789...` |
### Configuration
```bash
# Required - Komodo API Connection
export KOMODO_URL="https://komodo.example.com"
export KOMODO_API_KEY="your-api-key"
export KOMODO_API_SECRET="your-api-secret"
```
## Optional Environment Variables
| Variable | Description | Default | Example |
|----------|-------------|---------|---------|
| `KOMODO_TIMEOUT` | API request timeout (ms) | `30000` | `60000` |
| `KOMODO_RETRY_COUNT` | Number of retries on failure | `3` | `5` |
| `KOMODO_RETRY_DELAY` | Delay between retries (ms) | `1000` | `2000` |
| `KOMODO_LOG_LEVEL` | Logging verbosity | `info` | `debug` |
| `KOMODO_SSL_VERIFY` | Verify SSL certificates | `true` | `false` |
### Example with Optional Variables
```bash
# Required
export KOMODO_URL="https://komodo.example.com"
export KOMODO_API_KEY="your-api-key"
export KOMODO_API_SECRET="your-api-secret"
# Optional
export KOMODO_TIMEOUT="60000"
export KOMODO_RETRY_COUNT="5"
export KOMODO_LOG_LEVEL="debug"
```
## Authentication Pattern
The Komodo MCP server uses HMAC-based authentication:
1. **API Key**: Identifies the client application
2. **API Secret**: Used to sign requests for verification
### Authentication Flow
```
1. Client includes API Key in request header
2. Request body/params are signed with API Secret
3. Server verifies signature using stored secret
4. On success, request proceeds
5. On failure, 401 Unauthorized is returned
```
### Request Signing
Each API request must include:
```
Headers:
X-Komodo-Api-Key: <KOMODO_API_KEY>
X-Komodo-Timestamp: <unix_timestamp>
X-Komodo-Signature: <HMAC-SHA256(request_body + timestamp, KOMODO_API_SECRET)>
```
## Security Best Practices
### Do
- Store credentials in secure environment variables
- Use secrets management (HashiCorp Vault, AWS Secrets Manager, etc.)
- Rotate API keys periodically
- Use separate credentials for development/production
### Do Not
- Commit credentials to version control
- Log API secrets
- Share credentials across applications
- Use production credentials in development
## Environment File Template
Create a `.env` file (never commit this):
```bash
# .env - Komodo MCP Server Configuration
# Copy to .env.local and fill in values
# Required - Komodo API Connection
KOMODO_URL=
KOMODO_API_KEY=
KOMODO_API_SECRET=
# Optional - Timeouts and Retries
KOMODO_TIMEOUT=30000
KOMODO_RETRY_COUNT=3
KOMODO_RETRY_DELAY=1000
# Optional - Logging
KOMODO_LOG_LEVEL=info
# Optional - SSL
KOMODO_SSL_VERIFY=true
```
## MCP Server Configuration
When adding the Komodo MCP server to Claude, use the following configuration:
### Claude Desktop (macOS/Windows)
```json
{
"mcpServers": {
"komodo": {
"command": "node",
"args": ["path/to/komodo-mcp/dist/index.js"],
"env": {
"KOMODO_URL": "https://komodo.example.com",
"KOMODO_API_KEY": "your-api-key",
"KOMODO_API_SECRET": "your-api-secret"
}
}
}
}
```
### Claude Code
```bash
claude mcp add komodo -- node path/to/komodo-mcp/dist/index.js
```
Then set environment variables in your shell profile.
## Troubleshooting
### Connection Issues
| Error | Cause | Solution |
|-------|-------|----------|
| `ECONNREFUSED` | Server not reachable | Check `KOMODO_URL` is correct |
| `ETIMEDOUT` | Request timeout | Increase `KOMODO_TIMEOUT` |
| `CERT_NOT_VALID` | SSL certificate issue | Set `KOMODO_SSL_VERIFY=false` (dev only) |
### Authentication Issues
| Error | Cause | Solution |
|-------|-------|----------|
| `401 Unauthorized` | Invalid credentials | Verify API key and secret |
| `403 Forbidden` | Insufficient permissions | Check API key permissions |
| `Signature Mismatch` | Clock drift | Sync system time |
## Validation
Test your configuration:
```bash
# Set environment variables
export KOMODO_URL="https://komodo.example.com"
export KOMODO_API_KEY="your-key"
export KOMODO_API_SECRET="your-secret"
# Test connection (after implementation)
npx komodo-mcp test-connection
```
