@integrity-labs/cloud-broker

MCP server for the Augmented ephemeral cloud-access broker. Exposes the agent-facing tools (aws_request_access, aws_poll_grant, aws_release_access, aws_describe_scope, aws_preview_request, aws_get_credentials) that mint, poll, and release scoped, TTL-bounded cloud credentials for a single task.

v1 ships AWS support (STS AssumeRole under the hood; pair with the aws-cli toolkit or any AWS SDK as the consumer). All tools are namespaced aws_* so GCP, Azure, and Cloudflare can land in this same package as gcp_* / azure_* / cf_* siblings without colliding (ENG-4782).

See the PRD and the toolkit doc for the full design.

Tools

| Tool | Purpose | |---|---| | aws_describe_scope | Returns the team's resolved policy ceiling for an account — what the agent is allowed to ask for. Free, idempotent. | | aws_preview_request | Dry-run a candidate request: auto_approve / route_to_approver / hard_deny. Writes nothing. | | aws_request_access | Mint or queue a grant. On auto_approve you get secret_ref; on route_to_approver you get pending and a grant_id. | | aws_poll_grant | Single-shot status check. Escape hatch — the broker pushes resolution via direct-chat. | | aws_get_credentials | Fetch the AWS_* values for an active grant. Call after aws_request_access returns active or after the resolution-notification arrives. | | aws_release_access | Voluntarily release a grant before TTL. Idempotent. |

Environment

| Var | Purpose | |---|---| | AGT_HOST | Augmented API base URL (e.g. https://api.augmented.example). | | AGT_TOKEN | Pre-provisioned JWT (preferred). If set, used until expiry. | | AGT_API_KEY | Host API key (tlk_…). Used to refresh the JWT via /host/exchange when AGT_TOKEN is missing or expired. |

At least one of AGT_TOKEN or AGT_API_KEY is required.

Worked example

An agent that needs to read one S3 object:

// 1. Optional: inspect the envelope before guessing.
aws_describe_scope({ account_id: "123456789012" })

// 2. Optional: dry-run.
aws_preview_request({
  account_id: "123456789012",
  actions: ["s3:GetObject", "s3:ListBucket"],
  resources: ["arn:aws:s3:::reports/*", "arn:aws:s3:::reports"],
  regions: ["us-east-1"],
  ttl_seconds: 900
})
// → { "would": "auto_approve", "reason": null }

// 3. Mint.
aws_request_access({
  agent_id: "11111111-1111-4111-8111-111111111111",
  run_id: "22222222-2222-4222-8222-222222222222",
  account_id: "123456789012",
  actions: ["s3:GetObject", "s3:ListBucket"],
  resources: ["arn:aws:s3:::reports/*", "arn:aws:s3:::reports"],
  regions: ["us-east-1"],
  ttl_seconds: 900,
  reason: "fetch the daily reports CSV for the user"
})
// → { "grant_id": "...", "status": "active", "secret_ref": "secret_ref://aws/runs/<run_id>/<grant_id>", "expires_at": "..." }

// 4. Fetch the AWS_* values and use them.
aws_get_credentials({ grant_id: "..." })
// → { "grant_id": "...", "expires_at": "...", "credentials": { "access_key_id": "...", "secret_access_key": "...", "session_token": "..." } }
//    Bash: AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... AWS_SESSION_TOKEN=... aws s3 cp s3://reports/today.csv -

// 5. (Optional) release early.
aws_release_access({ grant_id: "..." })

If aws_request_access returns status: "pending", a human approver was paged. The broker pushes the resolution to you via direct-chat — save the grant_id, return control, and resume when the inbound message arrives. On denied, the denial_reason field explains why. aws_poll_grant is an escape hatch for explicit re-checks.

Running locally

pnpm --filter @integrity-labs/cloud-broker build
AGT_HOST=http://api.agt.localhost:1355 \
AGT_AGENT_ID=<your-agent-uuid> \
AGT_RUN_ID=<your-run-uuid> \
AGT_TOKEN=$YOUR_JWT \
node packages/cloud-broker/dist/index.js

The server speaks MCP over stdio. Wire it into your runtime adapter's .mcp.json — the toolkit ID is cloud-broker (registered in packages/supabase/seeds/toolkit-definitions.json).

Notes

• The MCP response strips inline credentials from aws_request_access — only the secret_ref pointer reaches the LLM. The runtime adapter resolves the pointer at AWS-SDK call time (or via aws_get_credentials) so credentials never enter the agent's transcript.
• Per PRD §6.3 v1 ships TTL-bounded revocation only. aws_release_access marks the grant revoked in the broker DB and tears down the secret_ref, but in-flight STS sessions remain valid in AWS until their TTL. v1.1 closes that gap with the aws:TokenIssueTime hard-revoke pattern.
• 0.6.0 hard-renamed the tools to the aws_* namespace (ENG-4782). Agents on cloud-broker ≤ 0.5.0 will see "tool not found" errors from the broker until they're re-provisioned with the new tool names. Re-run agt agent provision for any agent that has the cloud-broker MCP wired in.