MCP Tools Reference

Complete API documentation for all strata MCP tools.

Overview

The strata MCP server exposes 13 tools and 2 resources for infrastructure management.

Tool	Type	Purpose
`workspace_status()`	Query	Get workspace state and readiness
`validate_file()`	Query	Validate YAML against schema
`list_schemas()`	Query	List all supported document kinds
`get_schema()`	Query	Get JSON Schema for a kind
`scaffold_file()`	Action	Generate YAML from template
`build_plan()`	Preview	Dry-run: show what build would generate
`build_run()`	Action	Execute build and generate artifacts
`build_sbom()`	Action	Generate SBOM or dependency inventory
`deploy_plan()`	Preview	Dry-run: show what deploy would change
`deploy_status()`	Query	Get current infrastructure state
`deploy_health()`	Action	Run health checks on deployed stages
`deploy_history()`	Query	Get recent deployment history
`audit_query()`	Query	Query deployment audit logs

Query Tools (Read-Only)

These tools don’t modify anything. Safe to call anytime.

`workspace_status(work_path: str = None) → dict`

Return full workspace state: readiness phases, profiles, repos, integrations, and health.

Always call this first. The response tells you exactly what command to run next.

Parameters:

Parameter	Type	Default	Description
`work_path`	str	CWD	Workspace root path (override auto-detection)

Returns:

{
  "success": true,
  "data": {
    "workspace_path": "/path/to/workspace",
    "readiness": {
      "phase": 1,
      "next_step": {
        "hint": "Initialize repositories with: strata repo add ...",
        "command": "strata repo add"
      }
    },
    "active_profile": "production",
    "repositories": [
      {"name": "infrastructure", "path": "../infrastructure", "status": "ok"}
    ],
    "tools": {
      "terraform": {"available": true, "version": "1.5.0"},
      "helm": {"available": true, "version": "3.12.0"},
      "ansible": {"available": false}
    }
  },
  "errors": [],
  "messages": []
}

Example:

status = await mcp.call("workspace_status")
if status["data"]["readiness"]["phase"] >= 4:
    print("Ready to deploy!")
else:
    print(f"Next step: {status['data']['readiness']['next_step']['hint']}")

`validate_file(file_path: str, work_path: str = None, deep: bool = False) → dict`

Validate a strata YAML file against its kind-specific schema.

Two-phase validation:

Phase 1 (default): Structural validation (required fields, types, enums)
Phase 2 (deep=True): Cross-reference validation (requires active profile)

Parameters:

Parameter	Type	Default	Description
`file_path`	str	required	Path to YAML (absolute or relative to work_path)
`work_path`	str	CWD	Workspace root
`deep`	bool	False	Enable Phase 2 cross-reference validation

Returns:

{
  "success": true,
  "data": {
    "valid": true,
    "kind": "deployment",
    "name": "production-aks",
    "errors": [],
    "warnings": [
      "Provisioner 'terraform' not found in workspace configuration"
    ]
  },
  "errors": [],
  "messages": []
}

Example:

# Phase 1: Quick validation
result = await mcp.call("validate_file", {
    "file_path": "deploy/deploy-prod.yaml"
})

# Phase 2: Deep validation (checks cross-references)
result = await mcp.call("validate_file", {
    "file_path": "deploy/deploy-prod.yaml",
    "deep": True
})

if result["data"]["valid"]:
    print("✅ File is valid")
else:
    for error in result["data"]["errors"]:
        print(f"❌ {error}")

`list_schemas() → dict`

List all supported strata document kinds.

Parameters: None

Returns:

{
  "success": true,
  "data": {
    "kinds": [
      "deployment",
      "configuration",
      "environment",
      "firewall",
      "module",
      "namespace",
      "network",
      "dns",
      "provider",
      "resource",
      "workspace"
    ]
  },
  "errors": [],
  "messages": []
}

Example:

result = await mcp.call("list_schemas")
for kind in result["data"]["kinds"]:
    print(f"- {kind}")

`get_schema(kind: str) → dict`

Return the full JSON Schema for a strata document kind.

Parameters:

Parameter	Type	Default	Description
`kind`	str	required	Document kind (e.g., deployment, namespace)

Returns: JSON Schema (OpenAPI 3.0 format)

{
  "success": true,
  "data": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
      "apiVersion": {...},
      "kind": {...},
      "meta": {...},
      "spec": {...}
    },
    "required": ["apiVersion", "kind", "meta", "spec"]
  },
  "errors": [],
  "messages": []
}

Example:

schema = await mcp.call("get_schema", {"kind": "deployment"})

# Use schema to validate YAML locally
from jsonschema import validate
validate(instance=yaml_doc, schema=schema["data"])

`deploy_status(file: str, work_path: str = None, stage: str = None) → dict`

Return current infrastructure state (Terraform outputs) for a deployment.

Parameters:

Parameter	Type	Default	Description
`file`	str	required	Path to deployment YAML
`work_path`	str	CWD	Workspace root
`stage`	str	None	Limit to specific stage name

Returns:

{
  "success": true,
  "data": {
    "deployment": "deploy-prod.yaml",
    "stages": [
      {
        "name": "infrastructure",
        "status": "provisioned",
        "outputs": {
          "kubernetes_cluster_fqdn": "prod-aks.eastus.cloudapp.azure.com",
          "load_balancer_ip": "20.45.123.45",
          "resource_group_id": "/subscriptions/.../resourceGroups/prod"
        }
      }
    ]
  },
  "errors": [],
  "messages": []
}

Example:

status = await mcp.call("deploy_status", {"file": "deploy/deploy-prod.yaml"})

for stage in status["data"]["stages"]:
    print(f"Stage: {stage['name']}")
    for key, value in stage["outputs"].items():
        print(f"  {key}: {value}")

`deploy_history(work_path: str = None, lines: int = 20, operation: str = None) → dict`

Return recent deployment execution history.

Parameters:

Parameter	Type	Default	Description
`work_path`	str	CWD	Workspace root
`lines`	int	20	Number of history entries to return
`operation`	str	None	Filter by operation type: “run” or “destroy”

Returns:

{
  "success": true,
  "data": {
    "entries": [
      {
        "timestamp": "2026-07-05T14:23:45Z",
        "deployment": "deploy-prod.yaml",
        "operation": "run",
        "success": true,
        "duration_seconds": 514,
        "stages": ["infrastructure", "services"]
      }
    ],
    "count": 1
  },
  "errors": [],
  "messages": []
}

Example:

history = await mcp.call("deploy_history", {"lines": 10})

for entry in history["data"]["entries"]:
    status = "✅" if entry["success"] else "❌"
    print(f"{status} {entry['timestamp']} - {entry['deployment']} ({entry['duration_seconds']}s)")

`audit_query(work_path: str = None, last: int = 20, since: str = None, stage: str = None) → dict`

Query deployment audit logs.

Parameters:

Parameter	Type	Default	Description
`work_path`	str	CWD	Workspace root
`last`	int	20	Max entries to return
`since`	str	None	ISO timestamp: return entries after this time
`stage`	str	None	Filter to specific stage name

Returns:

{
  "success": true,
  "data": {
    "entries": [
      {
        "timestamp": "2026-07-05T14:23:45Z",
        "deployment": "deploy-prod.yaml",
        "stage": "infrastructure",
        "operation": "run",
        "success": true,
        "duration_seconds": 514,
        "user": "alice@example.com",
        "error": null
      }
    ],
    "count": 1
  },
  "errors": [],
  "messages": []
}

Example:

# Get last 50 failed deployments
query = await mcp.call("audit_query", {
    "last": 50,
    "since": "2026-06-01T00:00:00"
})

for entry in query["data"]["entries"]:
    if not entry["success"]:
        print(f"Failed: {entry['deployment']} - {entry['error']}")

Preview Tools (Dry-Run)

These tools show what would happen without making changes.

`build_plan(file: str, work_path: str = None) → dict`

Preview what the build would produce (dry-run).

Parameters:

Parameter	Type	Default	Description
`file`	str	required	Path to deployment YAML
`work_path`	str	CWD	Workspace root

Returns:

{
  "success": true,
  "data": {
    "deployment": "deploy-prod.yaml",
    "artifacts": {
      "platform": "generated",
      "terraform": ["main.tf", "variables.tf", "outputs.tf"],
      "configs": ["azure-aks.yaml"]
    },
    "stages": [
      {
        "name": "infrastructure",
        "provisioner": "terraform",
        "modules": [
          {"name": "azure/aks", "version": "1.2.3"},
          {"name": "azure/network", "version": "1.1.0"}
        ]
      }
    ],
    "messages": ["terraform modules will be installed from registry"]
  },
  "errors": [],
  "messages": []
}

Example:

plan = await mcp.call("build_plan", {"file": "deploy/deploy-prod.yaml"})

if plan["success"]:
    print(f"Build would generate: {plan['data']['artifacts']}")
else:
    print(f"Build would fail: {plan['errors']}")

`deploy_plan(file: str, work_path: str = None, stage: str = None) → dict`

Preview what the deployment would do (dry-run).

Shows Terraform plan output and resource changes.

Parameters:

Parameter	Type	Default	Description
`file`	str	required	Path to deployment YAML
`work_path`	str	CWD	Workspace root
`stage`	str	None	Limit plan to specific stage

Returns:

{
  "success": true,
  "data": {
    "deployment": "deploy-prod.yaml",
    "stages": [
      {
        "name": "infrastructure",
        "provisioner": "terraform",
        "plan": {
          "add": 11,
          "change": 0,
          "destroy": 0,
          "resources": [
            {
              "type": "azurerm_resource_group",
              "name": "prod",
              "action": "add"
            },
            {
              "type": "azurerm_kubernetes_cluster",
              "name": "prod",
              "action": "add"
            }
          ]
        },
        "estimated_cost": "$2,340/month",
        "estimated_duration": "15 minutes"
      }
    ]
  },
  "errors": [],
  "messages": []
}

⚠️ Important: Show this plan to the user. Only CLI can execute strata deploy run.

Example:

plan = await mcp.call("deploy_plan", {"file": "deploy/deploy-prod.yaml"})

if plan["success"]:
    for stage in plan["data"]["stages"]:
        print(f"Stage: {stage['name']}")
        print(f"  Changes: +{stage['plan']['add']} resources")
        print(f"  Cost: {stage['estimated_cost']}")
        print(f"  Duration: {stage['estimated_duration']}")
    print("\n✅ Preview complete. Review above and run:")
    print("  strata deploy run -f deploy/deploy-prod.yaml")
else:
    print(f"❌ Deployment would fail: {plan['errors']}")

Action Tools

These tools modify the workspace or generate outputs.

`scaffold_file(kind: str, name: str, extra_vars: dict = None) → dict`

Generate a strata YAML file from template (returns content, doesn’t write to disk).

Parameters:

Parameter	Type	Default	Description
`kind`	str	required	Document kind (deployment, namespace, etc.)
`name`	str	required	The `meta.name` value
`extra_vars`	dict	{}	Additional template variables (owner, version, etc.)

Returns:

{
  "success": true,
  "data": {
    "kind": "deployment",
    "name": "production-aks",
    "content": "apiVersion: strata.huybrechts.xyz/v1\nkind: deployment\n...",
    "suggested_path": "deployments/production-aks.yaml"
  },
  "errors": [],
  "messages": []
}

Example:

scaffold = await mcp.call("scaffold_file", {
    "kind": "deployment",
    "name": "staging-gke",
    "extra_vars": {
        "owner": "platform-team",
        "version": "1.0.0",
        "region": "us-central1"
    }
})

if scaffold["success"]:
    yaml_content = scaffold["data"]["content"]
    suggested_path = scaffold["data"]["suggested_path"]
    print(f"Save this content to: {suggested_path}")
    print(yaml_content)
else:
    print(f"Scaffold generation failed: {scaffold['errors']}")

`build_run(file: str, work_path: str = None) → dict`

Execute the full build pipeline and generate artifacts.

⚠️ Creates files in build/ directory. Safe to retry/delete.

Parameters:

Parameter	Type	Default	Description
`file`	str	required	Path to deployment YAML
`work_path`	str	CWD	Workspace root

Returns:

{
  "success": true,
  "data": {
    "deployment": "deploy-prod.yaml",
    "artifacts_path": "build/deploy-prod",
    "artifacts": {
      "platform": "build/deploy-prod/platform.json",
      "terraform": ["build/deploy-prod/terraform/main.tf"],
      "configs": ["build/deploy-prod/configs/azure-aks.yaml"]
    },
    "duration_seconds": 45,
    "stages": [{"name": "infrastructure", "status": "success"}]
  },
  "errors": [],
  "messages": []
}

Example:

build = await mcp.call("build_run", {"file": "deploy/deploy-prod.yaml"})

if build["success"]:
    print(f"✅ Build complete: {build['data']['artifacts_path']}")
    print(f"Duration: {build['data']['duration_seconds']}s")
else:
    print(f"❌ Build failed: {build['errors']}")

`build_sbom(file: str = None, work_path: str = None, scan: str = None, report: str = "inventory") → dict`

Generate SBOM (Software Bill of Materials) or dependency inventory.

Two modes:

Standard: Build SBOM from deployment (requires build_run first)
Scan: Scan directory directly (no deployment file needed)

Parameters:

Parameter	Type	Default	Description
`file`	str	None	Path to deployment YAML (standard mode)
`work_path`	str	CWD	Workspace root
`scan`	str	None	Directory to scan (scan mode)
`report`	str	“inventory”	Output format: “cyclonedx” (JSON) or “inventory” (text)

Returns (inventory mode):

{
  "success": true,
  "data": {
    "deployment": "deploy-prod.yaml",
    "components": [
      {
        "type": "container-image",
        "name": "azure-cli",
        "version": "2.50.0"
      },
      {
        "type": "helm-chart",
        "name": "nginx-ingress",
        "version": "4.8.3"
      },
      {
        "type": "python-library",
        "name": "requests",
        "version": "2.31.0"
      }
    ],
    "vulnerabilities": [
      {"component": "base-image", "cve": "CVE-2023-1234", "severity": "high"}
    ]
  },
  "errors": [],
  "messages": []
}

Example:

# Generate inventory for deployment
sbom = await mcp.call("build_sbom", {
    "file": "deploy/deploy-prod.yaml",
    "report": "inventory"
})

# Or scan a directory directly
sbom = await mcp.call("build_sbom", {
    "scan": "/path/to/repo",
    "report": "cyclonedx"
})

if sbom["success"]:
    for component in sbom["data"]["components"]:
        print(f"{component['type']}: {component['name']} ({component['version']})")

`deploy_health(file: str, work_path: str = None, stage: str = None) → dict`

Run health checks against provisioned deployment stages.

Executes HTTP GET or TCP checks defined in deployment YAML.

Parameters:

Parameter	Type	Default	Description
`file`	str	required	Path to deployment YAML
`work_path`	str	CWD	Workspace root
`stage`	str	None	Limit checks to specific stage

Returns:

{
  "success": true,
  "data": {
    "deployment": "deploy-prod.yaml",
    "overall_status": "healthy",
    "stages": [
      {
        "name": "infrastructure",
        "checks": [
          {
            "name": "api-endpoint",
            "type": "http",
            "target": "https://api.example.com/health",
            "status": "pass",
            "response_time_ms": 45
          },
          {
            "name": "database",
            "type": "tcp",
            "target": "db.example.com:5432",
            "status": "pass",
            "response_time_ms": 12
          }
        ],
        "passed": 2,
        "failed": 0
      }
    ]
  },
  "errors": [],
  "messages": []
}

Example:

health = await mcp.call("deploy_health", {"file": "deploy/deploy-prod.yaml"})

if health["success"]:
    print(f"Overall: {health['data']['overall_status']}")
    for stage in health["data"]["stages"]:
        print(f"  {stage['name']}: {stage['passed']}/{stage['passed'] + stage['failed']} checks passed")
else:
    print(f"Health check failed: {health['errors']}")

MCP Resources

`strata://schema/{kind}`

Auto-loaded resource: JSON Schema for a strata document kind.

Automatically loaded into AI context.

Example:

# Claude/AI automatically loads this
schema = resource("strata://schema/deployment")

`strata://workspace`

Auto-loaded resource: Current workspace state and readiness.

Automatically loaded into AI context.

Example:

# Claude/AI automatically loads this
workspace = resource("strata://workspace")

Error Handling

Success Field

Always check success first:

result = await mcp.call("validate_file", {"file_path": "deploy.yaml"})

if result["success"]:
    print(result["data"])
else:
    # Handle error
    print(f"Error: {result['errors']}")

Error Codes

Code	Meaning	Action
0	Success	Proceed normally
1	System/execution failure	Check `messages` for crash reason
2	Usage error (bad arguments)	Fix command syntax
3	Validation failure	Check `errors` array for specifics

Example Error Response

{
  "success": false,
  "data": null,
  "errors": [
    "File not found: deploy/deploy-prod.yaml",
    "Expected absolute or relative path"
  ],
  "messages": ["Validation failed during file loading"]
}

Rate Limits & Timeouts

No built-in rate limits in strata MCP
Host rate limits applied by Claude, Copilot, etc.
Long operations (build_run, deploy_plan) may take minutes
Recommended timeout: 10 minutes for deployment operations

MCP Tools Reference

Overview

Query Tools (Read-Only)

workspace_status(work_path: str = None) → dict

validate_file(file_path: str, work_path: str = None, deep: bool = False) → dict

list_schemas() → dict

get_schema(kind: str) → dict

deploy_status(file: str, work_path: str = None, stage: str = None) → dict

deploy_history(work_path: str = None, lines: int = 20, operation: str = None) → dict

audit_query(work_path: str = None, last: int = 20, since: str = None, stage: str = None) → dict

Preview Tools (Dry-Run)

build_plan(file: str, work_path: str = None) → dict

deploy_plan(file: str, work_path: str = None, stage: str = None) → dict

Action Tools

scaffold_file(kind: str, name: str, extra_vars: dict = None) → dict

build_run(file: str, work_path: str = None) → dict

build_sbom(file: str = None, work_path: str = None, scan: str = None, report: str = "inventory") → dict

deploy_health(file: str, work_path: str = None, stage: str = None) → dict

MCP Resources

strata://schema/{kind}

strata://workspace

Error Handling

Success Field

Error Codes

Example Error Response

Rate Limits & Timeouts

See Also

`workspace_status(work_path: str = None) → dict`

`validate_file(file_path: str, work_path: str = None, deep: bool = False) → dict`

`list_schemas() → dict`

`get_schema(kind: str) → dict`

`deploy_status(file: str, work_path: str = None, stage: str = None) → dict`

`deploy_history(work_path: str = None, lines: int = 20, operation: str = None) → dict`

`audit_query(work_path: str = None, last: int = 20, since: str = None, stage: str = None) → dict`

`build_plan(file: str, work_path: str = None) → dict`

`deploy_plan(file: str, work_path: str = None, stage: str = None) → dict`

`scaffold_file(kind: str, name: str, extra_vars: dict = None) → dict`

`build_run(file: str, work_path: str = None) → dict`

`build_sbom(file: str = None, work_path: str = None, scan: str = None, report: str = "inventory") → dict`

`deploy_health(file: str, work_path: str = None, stage: str = None) → dict`

`strata://schema/{kind}`

`strata://workspace`