Read the estate over MCP

terragucci mcp is a read-only Model Context Protocol server on stdio. It serves only what terragucci already wrote to the reports bucket and the repo, and runs no model of its own.

Result

An agent that answers “when did envs/prod/app last apply, and what did it change?” from the bucket:

{
  "project": "github.com/acme/infra",
  "root": "envs/prod/app",
  "commit": "ef7f8e50010c12dca8e20ecf90009638a8497f0d",
  "wave": 1,
  "approval": "approved",
  "applied": true,
  "report": "github.com/acme/infra/2026/10/ef7f8e50010c12dca8e20ecf90009638a8497f0d/tf-apply-wave-1",
  "result": { "path": "envs/prod/app", "status": "planned", "changes": [{ "address": "terraform_data.app", "action": "create" }] }
}

Prerequisites

You need	Why
reports.bucket set, and a pipeline that has run	the server reads the reports the stages copied there
terragucci estate and terragucci audit run on a schedule, for the estate, dora and audit tools	the server serves the files they write, and computes nothing
Read access to the bucket, in the environment the client starts the server from	the server takes credentials from its own environment, never from the agent

Steps

1. Give the server an identity that can read the bucket and nothing more, in the variables Reports lists.

   Store	Identity
   S3	AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or a role
   GCS	GOOGLE_APPLICATION_CREDENTIALS
   Azure Blob	AZURE_STORAGE_KEY, or an Entra ID identity

2. Add the server to your MCP client. From the repo’s root, where it reads terragucci.yml, the command line is:

   npx -y @intentius/terragucci mcp

   Outside the repo, name the bucket instead:

   npx -y @intentius/terragucci mcp --bucket s3://acme-plan-reports --bucket-prefix terragucci

   A client starts a stdio server with only a few variables of its own, so name the bucket’s credentials in the server’s env. A client that expands variables in its config, such as Claude Code’s .mcp.json, keeps the values in your shell:

   {
     "mcpServers": {
       "terragucci": {
         "command": "npx",
         "args": ["-y", "@intentius/terragucci", "mcp"],
         "env": {
           "AWS_ACCESS_KEY_ID": "${AWS_ACCESS_KEY_ID}",
           "AWS_SECRET_ACCESS_KEY": "${AWS_SECRET_ACCESS_KEY}",
           "AWS_REGION": "us-east-1"
         }
       }
     }
   }

3. Ask. The agent lists the tools and calls them:

   Ask	Tool
   when did a root last apply, and what changed	last_apply
   which runs ran on a commit, and their reports	index, then report
   where each wave of an applied commit stands	run_view
   which state version to restore	state_versions
   who approved what	audit
   how often you deploy, and how fast you restore	dora
   which wave waits, and the command to approve it	waiting

Refusals

A call	The answer
approve, apply, override, or any tool it does not list	an error: approvals belong to a person at a shell, and an approval made over MCP is refused
an argument the tool does not list, such as token	an error; credentials come from the server’s environment
a report path outside the bucket’s prefix	an error

The waiting tool prints each waiting wave’s terragucci approve command for a person to run; the server cannot run it. CLI commands lists each tool’s arguments.

MCP or --json

You want to	Use
read what terragucci wrote: reports, the estate, state versions, the audit trail, DORA figures	terragucci mcp
set terragucci up, check a config, write the pipeline, plan, run a response in dry run	the CLI with --json (JSON output)
approve, apply, override or merge	neither: a person does it

Next

• Set up with a coding agent gives the agent’s rules.
• See every project writes the estate page the estate tool reads.