AI access (MCP)

MCP is an open standard for giving an AI client access to a system’s data. StaleSweep implements the server half of it: you issue a credential, point a client at the StaleSweep endpoint, and the client can then read your scans, findings, savings and cost summaries as it answers you.

Step 1 — Issue a credential

Credentials live in Settings → AI access. Issuing one requires an admin role, and StaleSweepasks you to re-authenticate first — the same step-up it asks for before changing SSO settings or a member’s role, for the same reason: this mints a token that can read the whole account.

1. Go to Settings → AI access → Create credential and name it after the client that will use it (“Claude Desktop”, “work laptop”). One credential per client, so you can revoke a single machine later without disconnecting the rest.
2. Choose what it may read. All four are selected by default; clear any the client doesn’t need. See what each one covers below.
3. Choose a lifetime — 30, 90, 180 days or 1 year. There is no “never expires”: the credential nobody remembers to revoke is the one that outlives the laptop it was installed on.
4. Copy the token. It starts with mcp_ and is shown once: StaleSweep stores only a hash of it, so it cannot be shown again or recovered. If you lose it, revoke that credential and issue another.

Step 2 — Connect your client

MCP clients differ in where you put this, but they all need the same two things — the endpoint URL, and the credential as a bearer token:

• Endpoint: https://api.stalesweep.com/mcp
• Header: Authorization: Bearer mcp_…

The transport is JSON-RPC 2.0 over HTTP POST. Many clients take a JSON entry of roughly this shape; check your client’s own documentation for where the file lives and what it calls the fields.

{
  "mcpServers": {
    "stalesweep": {
      "type": "http",
      "url": "https://api.stalesweep.com/mcp",
      "headers": { "Authorization": "Bearer mcp_your_token_here" }
    }
  }
}

Checking it works

Your client should list the StaleSweep tools once it connects. To test the credential on its own, send the handshake every MCP session opens with:

curl -sS https://api.stalesweep.com/mcp \
  -H "Authorization: Bearer mcp_your_token_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "credential-check", "version": "1.0" }
    }
  }'

A response naming the server and the protocol version it agreed to means the credential works. A 401 means it is wrong, revoked or expired — the endpoint answers all three the same way on purpose, so a caller probing it learns nothing about which.

What it can read

Each choice at issue time turns on a group of tools. A client only sees the tools its credential allows, so an AI cannot be talked into using one you did not grant.

• Scans and realized savings: the scan history, each scan's status and headline numbers, and the savings summary. Also what a client uses to watch a running scan.
• Findings, resources and deletion-safety verdicts: the unused and wasteful resources themselves, with estimated monthly savings and whether each one is safe to delete.
• Actual AWS spend: the cost summary built from your Cost & Usage Report data.
• Report metadata: which report types exist. Report contents and PDFs are not exposed over MCP.

The tools themselves

• list_scans, get_scan, get_scan_status: the scan history and one scan in detail, plus a cheap status-only call for polling a scan that is still running.
• get_savings_summary: estimated and realized monthly savings across the account.
• list_findings, get_finding: the current estate — every connected AWS account's latest completed scan — filtered by resource type, region, severity or account, with the deletion-safety verdict for each.
• get_cost_summary: real AWS spend, when cost insights are turned on.
• list_report_types: the report types available on the Reports page.

Findings come back with the same deletion-safety verdict the app shows — safe, blocked, review, or refuted — and with the same honesty about what is unknown: a resource that could not be priced is reported as cost-unknown rather than as $0, so a client has no reason to describe it as free.

What it cannot do

• Change anything. Every tool is a read. There is no delete, no suppression, no scan trigger, no settings change — an AI client cannot act on your AWS account through StaleSweep.
• See another account. A credential is bound to the account it was issued in. Tenancy comes from the credential itself, never from anything the caller sends.
• Reach your AWS keys. StaleSweep's own AWS access is read-only and role-based, and none of it is exposed over MCP. See the security page for how that works.
• Read report contents. Only the list of report types is available. PDFs and their contents stay in the app and in the delivery channels you configure.

Revoking and expiry

Settings → AI access lists every credential with when it was last used, so you can tell a client that is still connected from one that was set up and forgotten. Revoke stops that credential on its next request — there is no cache to wait out — and the row stays, marked Revoked, so the audit trail still resolves. Issuing and revoking are both recorded in the audit log.

Limits

The endpoint is rate limited per account, not per client, so several connected clients share one budget:

• 300 requests per minute per account, counted across every credential it has.
• 100 rows per page on the list tools, 25 by default.
• 64 KB per request body.

A client that goes over gets a standard JSON-RPC error with a retry hint rather than a dropped connection. The protocol versions supported are 2025-06-18 and 2025-03-26; the server advertises tools only — no resources or prompts — and never asks your client to sample from its model.