Skip to content

cloudg mcp read

Reads one MCP resource in-process and prints its contents, with the policy applied as it would be for a client.

Resources are fetched by URI, such as cloudg://findings/summary or cloudg://assets/<ref>. cloudg mcp read lets you look at one from the shell, which helps when you are writing a policy or checking what an assistant will be shown.

Usage

cloudg mcp read [OPTIONS] URI

Options

Flag Value Default Description
URI (argument) TEXT none Required.
--principal-id TEXT none Principal id to call as.
--role TEXT none Call as a principal with this role (repeatable; default: the local user). Repeatable.
-c, --config TEXT none cloudg config.yaml (defaults to the parent command's config).
--policy TEXT none Policy profile name, or a YAML/JSON policy file. Environment: CLOUDG_MCP_POLICY.
--dataset [NAME=]PATH none Preload a dataset (findings.json, inventory-map.json...). Repeatable. Repeatable.
--prefix TEXT `` Prefix for tool and prompt names.
--include-category TEXT none Only expose these categories. Repeatable. Repeatable.
--exclude-category TEXT none Hide these categories. Repeatable. Repeatable.
--include-tool TEXT none Only expose these tools. Repeatable. Repeatable.
--exclude-tool TEXT none Hide these tools. Repeatable. Repeatable.
--read-only flag off Drop tools that write files, call cloud APIs, run scanners or are destructive.
--audit-log FILE none Append a JSONL audit trail (argument values are hashed). Environment: CLOUDG_MCP_AUDIT_LOG.
--timeout FLOAT 300.0 Per-call timeout in seconds.
--registry MODULE:ATTR none Serve a custom Registry (or a zero-argument factory returning one) instead of the built-in catalog.

Generated from the click definition in /opt/hostedtoolcache/Python/3.12.15/x64/lib/python3.12/site-packages/cloudg/mcp/cli.py, so it matches cloudg mcp read --help.

How it works

Like cloudg mcp call, each invocation builds a fresh layer from the shared options (see cloudg mcp serve), reads URI once as the chosen principal, prints the contents and exits. Most resources read the active dataset, so load one with --dataset on the same command line. Without a dataset, those resources fail:

$ cloudg mcp read cloudg://findings/summary
Error: No dataset is loaded. Call load_dataset(path=...) with an inventory-map.json / findings.json / scanner report, or map_inventory to collect live data.

The URI can be a fixed resource or a filled-in template. cloudg mcp resources lists both. For the asset templates, the reference can be the internal ID, a unique name, or a full ARN, and the ARN can be written as is or URL-encoded. Quote the URI in the shell, since ARNs contain : and / and some templates contain characters the shell treats specially.

Text contents are printed as they are, which for most resources is indented JSON and for some is another format: cloudg://ontology/turtle prints Turtle, cloudg://graph/graphml prints GraphML XML, and cloudg://docs/{topic} prints Markdown. Binary contents, if a resource returns any, are printed as their wire JSON with the base64 blob.

The policy decides what the principal may read. A resource it hides gives the same error as one that does not exist. For example, the strict profile hides the restricted Turtle export:

$ cloudg mcp read cloudg://ontology/turtle --policy strict --dataset prod=inventory/inventory-map.json
Error: Unknown resource: cloudg://ontology/turtle

The principal options (--role, --principal-id) work as on cloudg mcp tools. stdout carries only the contents, so the output can be piped or redirected.

Examples

Headline numbers of a dataset, by name. This capture uses the synthetic estate from the test suite and is cut after the first lines:

$ cloudg mcp read cloudg://datasets/prod/summary --dataset prod=inventory/inventory-map.json
{
  "dataset": "prod",
  "kind": "inventory",
  "source": "/home/me/estate/inventory/inventory-map.json",
  "loaded_at": "2026-10-09T16:24:08+00:00",
  "version": 0,
  "providers": [
    "aws",
    "azure",
    "gcp"
  ],
  "total_assets": 44,
  "total_edges": 56,
  "total_findings": 12,
  "open_findings": 11,
  "suppressed_findings": 1,
  ...
}

total_findings is not zero although only an inventory map was given: a findings.json in the same folder is loaded into the dataset.

Read one asset by ARN:

cloudg mcp read 'cloudg://assets/arn:aws:ec2:us-east-1:111111111111:instance/i-0bast' --dataset prod=./reports/inventory-map.json

List the open critical findings, highest risk first:

cloudg mcp read cloudg://findings/severity/CRITICAL --dataset prod=./reports/inventory-map.json

Export the ontology as Turtle for a triple store:

cloudg mcp read cloudg://ontology/turtle --dataset prod=./reports/inventory-map.json > estate.ttl

Export the graph for Gephi or yEd:

cloudg mcp read cloudg://graph/graphml --dataset prod=./reports/inventory-map.json > estate.graphml

See which documentation topics the server offers to assistants:

cloudg mcp read cloudg://docs

Check what the active policy does, as seen by a given role:

cloudg mcp read cloudg://policy --policy ./mcp-policy.yaml --role analyst

Exit codes

Code When
0 The contents were printed
1 The URI is unknown or hidden (Error: Unknown resource: URI), the resource failed (for example no dataset loaded), or the layer could not be built
2 Click rejected an option