Provides read-only analysis of proposed Terraform infrastructure changes from a Terraform plan JSON file. It identifies resource identities, action/type/mode counts, and coverage warnings through the analyze_terraform_plan tool, without executing Terraform or applying changes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@cloud-governance-mcp analyze plan.json and summarize the proposed infrastructure changes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An open-source Model Context Protocol (MCP) server for cloud infrastructure governance. The project is being built to help AI assistants inspect infrastructure, evaluate governance policies, and explain security and compliance findings.
The initial focus is Terraform plan JSON, with policy-as-code using Open Policy Agent (OPA) and Rego. The architecture separates MCP interfaces from the governance engine so future adapters can support read-only AWS inspection. The project demonstrates platform engineering, infrastructure security, policy-as-code, and MCP integration through small, tested increments.
The v0.1 target has three complementary tools:
Tool | Purpose | Status |
| Explain proposed changes through resource identities, action/type/mode counts, and coverage warnings. | Implemented |
| Evaluate a plan against governance rules and return structured findings with resource addresses, policy IDs, severity, and explanations. | Implemented; RDS encryption (AWS-RDS-001 v1.1.0), unrestricted SSH ingress (AWS-SG-001 v1.0.0) mandatory tags (AWS-TAG-001 v1.0.0), and S3 public-access protection (AWS-S3-001 v1.0.0) |
| Describe implemented governance policies, versions, severity, supported resources and configuration requirements. | Implemented; uses the shared evaluation catalog without OPA |
RDS coverage includes standalone instances and clusters, with conservative encryption inheritance for cluster members. SSH coverage includes inline security group rules, legacy rules and modern ingress rules with direct world-wide sources. Mandatory tags check Environment, Owner and Project by default, with startup overrides for five supported resource types. S3 checks four bucket-level protection flags, with conservative bucket/block association; unresolved links stay indeterminate.
Analysis explains changes; evaluation adds compliance decisions; policy listing describes the available rules. AWS connectivity is a later milestone.
Related MCP server: aws-safe-mcp
Terraform plan analysis is available locally over stdio. The first analysis
increment (A1–A7) is complete, with real MCP client/server tests, synthetic plans,
and a hands-on walkthrough. Package version is 0.1.0.dev0; all three tools are
available, with all four initial policy families implemented. Complete v0.1
acceptance consolidation remains the next milestone. Evaluation
uses pinned OPA 1.21.2. All tools operate locally without AWS credentials or
Terraform. Analysis and policy listing need no OPA configuration or installation.
Specification 004 adds cluster
encryption and conservative cluster-member associations. Unknown ARNs, ambiguous
targets or unproven AWS context yield indeterminate; live defaults are never
inferred. See the cluster walkthrough and
verification record.
Specification 005 implements
unrestricted SSH ingress and evaluation of two bundled policies. Omitting
policy_ids selected both at that checkpoint; explicit selection preserves that scope. See the
SSH walkthrough and verification record.
Specification 006 implements
mandatory resource tags, starting with Environment, Owner and Project.
At this checkpoint, omission selected three policies. See the
tag walkthrough and acceptance record.
Specification 007 implements S3 public-access protection. Omission now selects all four policies. Follow the S3 walkthrough and acceptance record.
From the repository directory, with uv installed:
uv sync --locked --no-editable
uv run --locked --no-editable python examples/client.py --list-tools
uv run --locked --no-editable python examples/client.pyThe first call lists all three implemented tools. The second analyzes our synthetic
mixed plan: 7 resources, 4 managed changes, and partial coverage because
one inventory resource has no reported action. Compare the
input plan with the
full example response.
The example client starts and stops its own server. No second terminal, AI model, API key, AWS credentials, Terraform or OPA is needed. Initial dependency/interpreter installation may need internet access; analysis itself is local.
Follow the hands-on walkthrough to understand the report, try other fixtures and safe failures, supply your own plan, and connect an MCP host. The client source shows the official SDK calls.
Follow OPA setup to install and checksum-verify the pinned local binary. Then evaluate the synthetic unencrypted RDS plan:
uv run --locked --no-editable python examples/client.py --evaluate --policy-id AWS-RDS-001 --plan-path unencrypted_rds.json --opa-path .tools/opa/1.21.2/opaThe result reports complete execution and a fail compliance finding for
aws_db_instance.example. Missing/unknown/sensitive encryption yields
indeterminate; engine failures are separate tool errors. See the
evaluation walkthrough and
saved full report.
Try --plan-path cluster_unencrypted.json for one cluster and two members:
three failed checks, with member remediation pointing to cluster encryption.
cluster_encrypted.json passes all three; cluster_unknown_arn.json reports a
passing cluster and two indeterminate members. New-resource plans commonly have
unknown ARNs, so this last case is an expected limitation.
For all four policies, try --evaluate --plan-path mixed_all_policies.json with
the same OPA path and no --policy-id. The four-resource plan produces 16
checks: six passes, one SSH failure and nine not-applicable checks. Uncertain network values
remain indeterminate unless another known predicate resolves the rule. This is
plan-based direct exposure checking; it does not inspect effective AWS reachability.
uv run --locked --no-editable python examples/client.py --list-policiesThis returns AWS-RDS-001, AWS-S3-001, AWS-SG-001 and AWS-TAG-001 metadata from the same catalog used by evaluation,
including supported types, severity and configuration requirements. TAG consumes
required_tag_keys with startup defaults; RDS/S3/SSH have no policy-specific settings.
It reads no plan and invokes no OPA process. Compare the
saved response or follow the
listing walkthrough. --list-tools discovers MCP
functions; --list-policies discovers governance rules.
To use the tools directly in Codex, follow the Codex stdio connection guide.
After setup, launch with an existing absolute directory containing plan files:
uv run --locked --no-editable cloud-governance-mcp --allowed-root /absolute/path/to/plansThe host calls analyze_terraform_plan with {"plan_path": "plan.json"}. Repeat
--allowed-root for more directories; relative plan paths use the first root.
The process waits for MCP messages on stdin, and stdout carries protocol frames
only. There is no terminal prompt or HTTP page. See
host process settings and
all CLI options.
Terraform plan JSON format major 1; state JSON, HCL and binary plans are rejected.
Generic provider identities, recursive modules and exact numeric/string instance keys. Inventories merge by resource address without double counting.
Create, update, delete, both replacement orders, no-op and data-source read.
Inventory-only resources remain unreported; they are never guessed to be no-op.
Deterministic public reports with fixed warnings/errors. complete/partial
describes coverage of the supplied plan, not compliance or deployment state.
Explicit allowed roots; no traversal, symlinks beneath roots, special files or
implicit current-directory access. Input/depth/resource/output limits and one
active analysis are enforced. Run --help for startup options.
Attribute values, variables, outputs and internal sensitive/unknown paths are absent from responses. Resource identities are intentionally returned.
No tool executes Terraform, applies changes, or connects to AWS. Provide a completed, stable plan file; it does not freeze concurrent file writes.
Development uses Python 3.14.7 with locked dependencies and a src/ layout.
The package requires Python 3.14+. Secure file loading targets macOS/Linux;
macOS arm64 is verified, Linux execution remains unverified here, and unsupported
platforms fail startup. The regular-install --no-editable workflow avoids an
observed local macOS editable-import issue. See development notes.
Install the pinned OPA runtime for the full suite, which includes real policy tests. The documented analysis-only command works without it. Current verification: 1,184 Python tests and 37 Rego tests pass.
uv run --locked --no-editable pytest
uv run --locked --no-editable ruff check .
uv run --locked --no-editable ruff format --check .
uv buildThe original analysis increment had 521 passing tests, including real MCP stdio and example-client tests. The acceptance record maps AN-01–AN-15 to tests and records versions, independent wheel/stdio checks, and tested limitations. The synthetic fixtures use fake values; illustrative Terraform configuration is not executed by tests. No OPA setup or policy tests belong to this analysis increment.
Milestone | Scope | Status |
First analysis increment | Local Terraform plan analysis, safe file loading, deterministic reports, MCP stdio, examples and tests. | Complete |
v0.1 | All three tools and the four initial governance policy families using OPA/Rego. | In progress |
v0.2 | Docker packaging, expanded policies, GitHub Actions CI/CD, and contributor documentation. | Planned |
v0.3 | Read-only AWS discovery through boto3, cross-account support, and mocked integration tests. | Planned |
v0.4+ | Potential drift analysis, module documentation retrieval, cost/operational insights, and optional RAG. | Exploratory |
Future capabilities are not included in the current server. See the release roadmap for scope and completion criteria.
Stack: Python 3.14+, the official MCP Python SDK, Pydantic, AnyIO, uv, pytest and Ruff. Policy evaluation uses OPA/Rego.
License: Apache 2.0.
Summarize resource identities and proposed actions from a local Terraform plan JSON file in an allowed directory. Returns no resource attribute values and performs no compliance evaluation or infrastructure changes.
| Name | Required | Description | Default |
|---|---|---|---|
| plan_path | Yes | Local path within an allowed root. |
| Name | Required | Description |
|---|---|---|
| summary | Yes | |
| warnings | Yes | |
| resources | Yes | |
| format_version | Yes | |
| schema_version | No | |
| analysis_status | Yes | |
| terraform_version | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, closed-world, non-destructive behavior, so the bar is lower; the description still adds meaningful context by stating the output deliberately omits resource attribute values and that no infrastructure changes occur. It does not cover error behavior for missing/invalid plan files or path-allowlist rejection, which would be the next valuable additions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, and the second sentence exists specifically to set negative expectations about output and side effects. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With annotations, full schema coverage, a single required parameter, and an output schema, the description covers what an agent needs to select and call it. A minor gap is that it doesn't state the plan must be the JSON rendering (e.g., from `terraform show -json`) rather than a binary plan file.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single plan_path parameter is documented as 'Local path within an allowed root.' The description's phrase 'local Terraform plan JSON file in an allowed directory' adds only slight clarification (JSON format) beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (summarize), resource (Terraform plan JSON), and the exact content returned (resource identities and proposed actions), plus scope constraints (local file, allowed directory). This is clearly distinguishable from evaluate_terraform_policies by the explicit disclaimer that no compliance evaluation occurs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description bounds when to use it by negating the sibling capability ('performs no compliance evaluation or infrastructure changes'), which implicitly routes compliance questions to evaluate_terraform_policies. It does not name the alternative tool explicitly or describe the plan-file prerequisite workflow, so it stops short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Evaluate bundled governance policies against a local Terraform plan JSON file in an allowed directory. Return policy findings, uncertainty and coverage without resource attribute values. Requires configured OPA; does not inspect or modify deployed infrastructure.
| Name | Required | Description | Default |
|---|---|---|---|
| plan_path | Yes | ||
| policy_ids | No |
| Name | Required | Description |
|---|---|---|
| errors | Yes | |
| summary | Yes | |
| findings | Yes | |
| warnings | Yes | |
| policy_scope | Yes | |
| format_version | Yes | |
| schema_version | No | |
| compliance_status | Yes | |
| evaluation_status | Yes | |
| terraform_version | No | |
| selected_policy_ids | Yes | |
| indeterminate_checks | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry readOnly/idempotent/non-destructive/closed-world, so the lower bar applies; the description still adds real context the annotations don't: an OPA dependency, a directory allow-list restriction, and that returned findings deliberately exclude resource attribute values. It stops short of describing cost, rate limits, or failure modes on an invalid plan file.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with the core action and target front-loaded and zero filler. The sentence about return contents is slightly redundant given an output schema exists, but it carries a real caveat about withheld attribute values.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a full output schema and rich annotations, the description covers the operational envelope (OPA required, directory restriction, no live infrastructure access) well. The one material gap is that policy selection behavior is left entirely to the schema's top-level note, so an agent reading only the description would not know how to scope which policies run.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the two parameters, so the description must compensate and largely does not. 'plan_path' is only obliquely implied by 'a local Terraform plan JSON file in an allowed directory'; 'policy_ids' (array, max 4, with non-obvious omission-vs-null semantics) is never mentioned in the description at all.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (evaluate), specific resource (bundled governance policies) and a specific target (a local Terraform plan JSON file in an allowed directory). This is clearly distinguishable from analyze_terraform_plan (plan analysis) and list_policies (enumeration) without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Establishes the preconditions for use: the plan must already be a local JSON file in an allowed directory and OPA must be configured. It also carves out the boundary ('does not inspect or modify deployed infrastructure'), but never names analyze_terraform_plan or list_policies as alternatives or states when to prefer them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the bundled governance policies available for Terraform plan evaluation, including their versions, severity, supported resources, scope and required configuration. Does not read plans or invoke OPA.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| policies | Yes | |
| schema_version | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds useful negative behavior ('does not read plans or invoke OPA'), which is genuine value beyond annotations, but it says nothing about cost, side effects on caches, or whether the policy set can change between calls.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. The positive scope comes first and the exclusions follow immediately, so an agent gets the useful content up front.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-shape explanation is unnecessary, and annotations plus the zero-param schema cover the rest. The description is nearly complete; a short pointer to evaluate_terraform_policies as the natural next step would close the only gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so baseline is 4. Both the description and the schema note that listing takes no filters, paths or configuration, which preempts an agent trying to narrow the result set.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List the bundled governance policies') and scopes the result set ('available for Terraform plan evaluation'), then enumerates what the listing exposes. The closing sentence separates it from analyze_terraform_plan and evaluate_terraform_policies by denying plan-reading and OPA invocation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'available for Terraform plan evaluation' plus the explicit exclusion of plan reading and OPA invocation steers an agent toward this as a discovery step rather than an execution step. It stops short of naming evaluate_terraform_policies as the follow-up call, so the routing is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0analyze_terraform_planevaluate_terraform_policieslist_policiesScored across 3 tools
analyze_terraform_plan and evaluate_terraform_policies both consume a local plan JSON file, which creates surface-level overlap, but the descriptions draw a clear line (summarize identities/actions vs. run OPA policy findings, with explicit 'performs no compliance evaluation' disclaimers). list_policies is unambiguously distinct as pure catalog discovery.
All three tools use a consistent snake_case verb_noun pattern (analyze_/evaluate_/list_) with the resource clearly stated. The noun varies appropriately with the target object (terraform_plan, terraform_policies, policies) rather than indicating inconsistency.
Three tools is on the thin side, but the server has a narrow, well-defined scope (read-only Terraform plan governance) and each tool maps to a distinct phase: discovery, structural summary, policy evaluation. No tool feels redundant or filler.
The core lifecycle for a read-only governance server is covered: list what policies exist, inspect what a plan will do, and evaluate it. Minor gaps remain — no tool to enumerate plan files in the allowed directories and no way to fetch full detail for a single policy — but agents can work around these by supplying paths and relying on list_policies output.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
MCP server for generating rough-draft project plans from natural-language prompts.
Public, read-only MCP server for FarmNeural company facts, packages, and capabilities.
Read-only MCP server for AIStatusDashboard status, incidents, metrics, and fallback recommendations.
