Skip to main content

Read CGR attestations

A CGR attestation is a Foundation-signed statement about an agent's Capability-Grounded Reputation — a track record grounded in that agent's own recorded judgments and their real outcomes. This page is how a consumer reads one. You never have to trust the server that serves it: pin the Foundation issuer key once and verify every attestation yourself.

There are two ways to read, over the same signed envelope:

  • Remote MCP server — com.grafomem/cgr-read. An MCP client (Claude, a Vercel AI SDK agent, any MCP client) connects to a URL; no install.
  • REST — GET /v1/cgr/read/attestation.

Both are authenticated today. Public, unauthenticated serving is gated behind a signed boundary review and is not open.

Authentication​

Every read requires a GRAFOMEM Cloud tenant API key with the cgr:read scope.

  • MCP: send the key as a bearer token — Authorization: Bearer <YOUR_TENANT_KEY>.
  • REST: send it as X-API-Key: <YOUR_TENANT_KEY> (a bearer Authorization header also works).

The subject you ask about does not have to be your own agent; the scope authorizes reading attestations on your tenant's substrate.

The remote MCP server (com.grafomem/cgr-read)​

Connect an MCP client to the streamable-HTTP endpoint:

https://mcp.grafomem.com/mcp

It exposes three read-only tools.

cgr_get_attestation(subject, domain?)​

Read the signed attestation for a subject. subject is an agent identity — a 64-hex public key, a did:key:…, or a handle (facet@territory). domain is an optional capability domain (e.g. deploy-verification) to match against the subject's captured evidence.

Returns the envelope. An unknown subject, or a domain the subject has no captured evidence in, returns an explicit no_evidence result — never a default score.

cgr_list_domains(subject)​

List the distinct capability domains in which a subject has captured CGR evidence. Read-only; returns no scores.

cgr_verify_instructions()​

Return pointers for verifying an attestation yourself, offline, against the pinned issuer key: the verifier library, the recipe URL, and the pinned issuer public key. See Verify (offline).

The envelope​

cgr_get_attestation (and GET /v1/cgr/read/attestation) return an envelope in which the score is inseparable from its evidence — a bare score is never returned on its own. The authoritative copies of the score, its masses, and freshness are signed inside attestation.

{
  "surface_version": "cgr-read/1",
  "result": "attestation",
  "attestation": { /* Foundation-signed cgr.attestation.v3 — verify THIS */ },
  "score": 0.8,              // convenience echo; authoritative copy signed in attestation
  "evidence_mass": 5.0,      // pooled n = α+β backing the score
  "n_resolved": 3,           // pooled resolved-outcome count backing the score
  "scoring_scope": "pooled", // the score pools ALL judgment evidence — NOT per-domain
  "requested_domain": "deploy-verification",
  "domain_n_resolved": 2,    // resolved outcomes IN the requested domain (backs the MATCH)
  "freshness": { "as_of": "…", "last_resolved_at": "…", "age_ms": 123, "stale": false },
  "issuer": { "issuer": "gns-foundation", "issuer_key_id": "<hex>", "schema": "cgr.attestation.v3" },
  "continuity": { "status": "verified|asserted|unverified", "advisory": true },
  "verify": { "recipe_url": "https://docs.grafomem.com/cgr/verify/", "lib": "@gns-foundation/cgr-verify", "issuer_pubkey": "<hex>" }
}

Read both evidence masses. n_resolved / evidence_mass (pooled) back the score; domain_n_resolved backs the domain match. scoring_scope: "pooled" states plainly that the score is not domain-specific — per-domain scoring is a later phase, and a response never implies a per-domain score exists before it does. All three markers are inside the signed body, so an intermediary cannot rewrite a pooled score into a domain-specific one.

No evidence​

An unknown subject, or a domain with no captured evidence, returns:

{ "surface_version": "cgr-read/1", "result": "no_evidence", "reason": "…", "score": null, "evidence_mass": null }

Never a default score, never 0.5, never an empty attestation.

Verify it yourself​

The envelope is designed so you never trust the server. Verify the signed attestation against a pinned Foundation issuer key:

import { verifyCGRAttestation } from '@gns-foundation/cgr-verify';
const res = await verifyCGRAttestation(envelope.attestation, PINNED_FOUNDATION_KEY,
                                       { expectedKey: envelope.attestation.subject_key });
if (!res.valid) throw new Error(res.reason);   // do not trust the score until this passes

The continuity field is advisory — for full key-rotation continuity, re-walk GET /v1/cgr/rotations yourself. Full recipe and cross-language golden fixtures: Verify a CGR attestation (offline).