provisioning/docs/src/ai/mcp-integration.md

# Model Context Protocol (MCP) Integration

**Status**: ✅ Production-Ready (MCP 0.6.0+, integrated with Claude, compatible with all LLMs)

The MCP server provides standardized Model Context Protocol integration, allowing external LLMs (Claude, GPT-4, local models) to access provisioning
platform capabilities as tools. This enables complex multi-step workflows, tool composition, and integration with existing LLM applications.

## Architecture Overview

The MCP integration follows the Model Context Protocol specification:

```bash
┌──────────────────────────────────────────────────────────────┐
│ External LLM (Claude, GPT-4, etc.)                           │
└────────────────────┬─────────────────────────────────────────┘
                     │
                     │ Tool Calls (JSON-RPC)
                     ▼
┌──────────────────────────────────────────────────────────────┐
│ MCP Server (provisioning/platform/crates/mcp-server)         │
│                                                              │
│ ┌───────────────────────────────────────────────────────┐    │
│ │ Tool Registry                                         │    │
│ │ - generate_config(description, schema)                │    │
│ │ - validate_config(config)                             │    │
│ │ - search_docs(query)                                  │    │
│ │ - troubleshoot_deployment(logs)                       │    │
│ │ - get_schema(name)                                    │    │
│ │ - check_compliance(config, policy)                    │    │
│ └───────────────────────────────────────────────────────┘    │
│                         │                                    │
│                         ▼                                    │
│ ┌───────────────────────────────────────────────────────┐    │
│ │ Implementation Layer                                  │    │
│ │ - AI Service client (ai-service port 8083)            │    │
│ │ - Validator client                                    │    │
│ │ - RAG client (SurrealDB)                              │    │
│ │ - Schema loader                                       │    │
│ └───────────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────────┘
```

## MCP Server Launch

The MCP server is started as a stdio-based service:

```bash
# Start MCP server (stdio transport)
provisioning-mcp-server --config /etc/provisioning/ai.toml

# With debug logging
RUST_LOG=debug provisioning-mcp-server --config /etc/provisioning/ai.toml

# In Claude Desktop configuration
~/.claude/claude_desktop_config.json:
{
  "mcpServers": {
    "provisioning": {
      "command": "provisioning-mcp-server",
      "args": ["--config", "/etc/provisioning/ai.toml"],
      "env": {
        "PROVISIONING_TOKEN": "your-auth-token"
      }
    }
  }
}
```

## Available Tools

### 1. Config Generation

**Tool**: `generate_config`

Generate infrastructure configuration from natural language description.

```json
{
  "name": "generate_config",
  "description": "Generate a Nickel infrastructure configuration from a natural language description",
  "inputSchema": {
    "type": "object",
    "properties": {
      "description": {
        "type": "string",
        "description": "Natural language description of desired infrastructure"
      },
      "schema": {
        "type": "string",
        "description": "Target schema name (e.g., 'database', 'kubernetes', 'network'). Optional."
      },
      "format": {
        "type": "string",
        "enum": ["nickel", "toml"],
        "description": "Output format (default: nickel)"
      }
    },
    "required": ["description"]
  }
}
```

**Example Usage**:

```bash
# Via MCP client
mcp-client provisioning generate_config 
  --description "Production PostgreSQL cluster with encryption and daily backups" 
  --schema database

# Claude desktop prompt:
# @provisioning: Generate a production PostgreSQL setup with automated backups
```

**Response**:

```json
{
  database = {
    engine = "postgresql",
    version = "15.0",
    
    instance = {
      instance_class = "db.r6g.xlarge",
      allocated_storage_gb = 100,
      iops = 3000,
    },
    
    security = {
      encryption_enabled = true,
      encryption_key_id = "kms://prod-db-key",
      tls_enabled = true,
      tls_version = "1.3",
    },
    
    backup = {
      enabled = true,
      retention_days = 30,
      preferred_window = "03:00-04:00",
      copy_to_region = "us-west-2",
    },
    
    monitoring = {
      enhanced_monitoring_enabled = true,
      monitoring_interval_seconds = 60,
      log_exports = ["postgresql"],
    },
  }
}
```

### 2. Config Validation

**Tool**: `validate_config`

Validate a Nickel configuration against schemas and policies.

```json
{
  "name": "validate_config",
  "description": "Validate a Nickel configuration file",
  "inputSchema": {
    "type": "object",
    "properties": {
      "config": {
        "type": "string",
        "description": "Nickel configuration content or file path"
      },
      "schema": {
        "type": "string",
        "description": "Schema name to validate against (optional)"
      },
      "strict": {
        "type": "boolean",
        "description": "Enable strict validation (default: true)"
      }
    },
    "required": ["config"]
  }
}
```

**Example Usage**:

```bash
# Validate configuration
mcp-client provisioning validate_config 
  --config "$(cat workspaces/prod/database.ncl)"

# With specific schema
mcp-client provisioning validate_config 
  --config "workspaces/prod/kubernetes.ncl" 
  --schema kubernetes
```

**Response**:

```json
{
  "valid": true,
  "errors": [],
  "warnings": [
    "Consider enabling automated backups for production use"
  ],
  "metadata": {
    "schema": "kubernetes",
    "version": "1.28",
    "validated_at": "2025-01-13T10:45:30Z"
  }
}
```

### 3. Documentation Search

**Tool**: `search_docs`

Search infrastructure documentation using RAG system.

```json
{
  "name": "search_docs",
  "description": "Search provisioning documentation for information",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query (natural language)"
      },
      "top_k": {
        "type": "integer",
        "description": "Number of results (default: 5)"
      },
      "doc_type": {
        "type": "string",
        "enum": ["guide", "schema", "example", "troubleshooting"],
        "description": "Filter by document type (optional)"
      }
    },
    "required": ["query"]
  }
}
```

**Example Usage**:

```bash
# Search documentation
mcp-client provisioning search_docs 
  --query "How do I configure PostgreSQL with replication?"

# Get examples
mcp-client provisioning search_docs 
  --query "Kubernetes networking" 
  --doc_type example 
  --top_k 3
```

**Response**:

```json
{
  "results": [
    {
      "source": "provisioning/docs/src/guides/database-replication.md",
      "excerpt": "PostgreSQL logical replication enables streaming of changes...",
      "relevance": 0.94,
      "section": "Setup Logical Replication"
    },
    {
      "source": "provisioning/schemas/database.ncl",
      "excerpt": "replication = { enabled = true, mode = \"logical\", ... }",
      "relevance": 0.87,
      "section": "Replication Configuration"
    }
  ]
}
```

### 4. Deployment Troubleshooting

**Tool**: `troubleshoot_deployment`

Analyze deployment failures and suggest fixes.

```json
{
  "name": "troubleshoot_deployment",
  "description": "Analyze deployment logs and suggest fixes",
  "inputSchema": {
    "type": "object",
    "properties": {
      "deployment_id": {
        "type": "string",
        "description": "Deployment ID (e.g., 'deploy-2025-01-13-001')"
      },
      "logs": {
        "type": "string",
        "description": "Deployment logs (optional, if deployment_id not provided)"
      },
      "error_analysis_depth": {
        "type": "string",
        "enum": ["shallow", "deep"],
        "description": "Analysis depth (default: deep)"
      }
    }
  }
}
```

**Example Usage**:

```bash
# Troubleshoot recent deployment
mcp-client provisioning troubleshoot_deployment 
  --deployment_id "deploy-2025-01-13-001"

# With custom logs
mcp-client provisioning troubleshoot_deployment 
| --logs "$(journalctl -u provisioning --no-pager | tail -100)" |
```

**Response**:

```json
{
  "status": "failure",
  "root_cause": "Database connection timeout during migration phase",
  "analysis": {
    "phase": "database_migration",
    "error_type": "connectivity",
    "confidence": 0.95
  },
  "suggestions": [
    "Verify database security group allows inbound on port 5432",
    "Check database instance status (may be rebooting)",
    "Increase connection timeout in configuration"
  ],
  "corrected_config": "...generated Nickel config with fixes...",
  "similar_issues": [
    "[https://docs/troubleshooting/database-connectivity.md"](https://docs/troubleshooting/database-connectivity.md")
  ]
}
```

### 5. Get Schema

**Tool**: `get_schema`

Retrieve schema definition with examples.

```json
{
  "name": "get_schema",
  "description": "Get a provisioning schema definition",
  "inputSchema": {
    "type": "object",
    "properties": {
      "schema_name": {
        "type": "string",
        "description": "Schema name (e.g., 'database', 'kubernetes')"
      },
      "format": {
        "type": "string",
        "enum": ["schema", "example", "documentation"],
        "description": "Response format (default: schema)"
      }
    },
    "required": ["schema_name"]
  }
}
```

**Example Usage**:

```bash
# Get schema definition
mcp-client provisioning get_schema --schema_name database

# Get example configuration
mcp-client provisioning get_schema 
  --schema_name kubernetes 
  --format example
```

### 6. Compliance Check

**Tool**: `check_compliance`

Verify configuration against compliance policies (Cedar).

```json
{
  "name": "check_compliance",
  "description": "Check configuration against compliance policies",
  "inputSchema": {
    "type": "object",
    "properties": {
      "config": {
        "type": "string",
        "description": "Configuration to check"
      },
      "policy_set": {
        "type": "string",
        "description": "Policy set to check against (e.g., 'pci-dss', 'hipaa', 'sox')"
      }
    },
    "required": ["config", "policy_set"]
  }
}
```

**Example Usage**:

```bash
# Check against PCI-DSS
mcp-client provisioning check_compliance 
  --config "$(cat workspaces/prod/database.ncl)" 
  --policy_set pci-dss
```

## Integration Examples

### Claude Desktop (Most Common)

```bash
~/.claude/claude_desktop_config.json:
{
  "mcpServers": {
    "provisioning": {
      "command": "provisioning-mcp-server",
      "args": ["--config", "/etc/provisioning/ai.toml"],
      "env": {
        "PROVISIONING_API_KEY": "sk-...",
        "PROVISIONING_BASE_URL": "[http://localhost:8083"](http://localhost:8083")
      }
    }
  }
}
```

**Usage in Claude**:

```bash
User: I need a production Kubernetes cluster in AWS with automatic scaling

Claude can now use provisioning tools:
I'll help you create a production Kubernetes cluster. Let me:
1. Search the documentation for best practices
2. Generate a configuration template
3. Validate it against your policies
4. Provide the final configuration
```

### OpenAI Function Calling

```bash
import openai

tools = [
    {
        "type": "function",
        "function": {
            "name": "generate_config",
            "description": "Generate infrastructure configuration",
            "parameters": {
                "type": "object",
                "properties": {
                    "description": {
                        "type": "string",
                        "description": "Infrastructure description"
                    }
                },
                "required": ["description"]
            }
        }
    }
]

response = openai.ChatCompletion.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Create a PostgreSQL database"}],
    tools=tools
)
```

### Local LLM Integration (Ollama)

```bash
# Start Ollama with provisioning MCP
OLLAMA_MCP_SERVERS=provisioning://localhost:3000 
  ollama serve

# Use with llama2 or mistral
curl [http://localhost:11434/api/generate](http://localhost:11434/api/generate) 
  -d '{
    "model": "mistral",
    "prompt": "Create a Kubernetes cluster",
    "tools": [{"type": "mcp", "server": "provisioning"}]
  }'
```

## Error Handling

Tools return consistent error responses:

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Configuration has 3 validation errors",
    "details": [
      {
        "field": "database.version",
        "message": "PostgreSQL version 9.6 is deprecated",
        "severity": "error"
      },
      {
        "field": "backup.retention_days",
        "message": "Recommended minimum is 30 days for production",
        "severity": "warning"
      }
    ]
  }
}
```

## Performance

|  | Operation | Latency | Notes |  |
|  | ----------- | --------- | ------- |  |
|  | generate_config | 2-5s | Depends on LLM and config complexity |  |
|  | validate_config | 500-1000ms | Parallel schema validation |  |
|  | search_docs | 300-800ms | RAG hybrid search |  |
|  | troubleshoot | 3-8s | Depends on log size and analysis depth |  |
|  | get_schema | 100-300ms | Cached schema retrieval |  |
|  | check_compliance | 500-2000ms | Policy evaluation |  |

## Configuration

See [Configuration Guide](configuration.md) for MCP-specific settings:

- MCP server port and binding
- Tool registry customization
- Rate limiting for tool calls
- Access control (Cedar policies)

## Security

### Authentication

- Tools require valid provisioning API token
- Token scoped to user's workspace
- All tool calls authenticated and logged

### Authorization

- Cedar policies control which tools user can call
- Example: `allow(principal, action, resource)` when `role == "admin"`
- Detailed audit trail of all tool invocations

### Data Protection

- Secrets never passed through MCP
- Configuration sanitized before analysis
- PII removed from logs sent to external LLMs

## Monitoring and Debugging

```bash
# Monitor MCP server
provisioning admin mcp status

# View MCP tool calls
provisioning admin logs --filter "mcp_tools" --tail 100

# Debug tool response
RUST_LOG=provisioning::mcp=debug provisioning-mcp-server
```

## Related Documentation

- [Architecture](architecture.md) - AI system overview
- [RAG System](rag-system.md) - Documentation search
- [Configuration](configuration.md) - MCP setup
- [API Reference](api-reference.md) - Detailed API endpoints
- [ADR-015](../architecture/adr/adr-015-ai-integration-architecture.md) - Design decisions

---

**Last Updated**: 2025-01-13
**Status**: ✅ Production-Ready
**MCP Version**: 0.6.0+
**Supported LLMs**: Claude, GPT-4, Llama, Mistral, all MCP-compatible models