The audit chain
Nebbos keeps hash-chained, tamper-evident records of the tool calls made through the Nebbos MCP and of the changes made through the platform API. Each record carries the SHA-256 hash of the record before it, so changing an earlier record breaks the link to every record that follows. This page describes what is recorded today, what each record holds, how your team checks a record, a range or the whole chain, and the limits that still apply.
This page describes the platform as built on 9 November 2026. Read-only platform API requests are not recorded yet, verification results are not signed, and there is no offline verifier yet. See Current limits.
What is recorded
| Source | What is recorded | How it enters the chain |
|---|---|---|
| MCP tool calls | Every call made through the Nebbos MCP, by a Pearl or a person, reads included, with its outcome. Refused and denied calls are recorded too. | The record is written to a durable queue before the tool response returns. A background chain builder hashes it into the chain, normally within about a minute. |
| Platform API changes | Every POST, PUT, PATCH and DELETE request to the platform API. | Queued by the API after the request completes and written by a background job. |
Each client has its own chain for each source. Writers take a per-client lock while they read the latest hash and append, so two writers cannot fork a chain.
Read-only (GET) requests to the platform API are not recorded yet. Changes made in the web app by signed-in people have been recorded since 4 November 2026; some made before that date have no record.
Record contents
MCP tool-call records
These fields are stored as columns:
| Field | Meaning |
|---|---|
id | Record identifier (UUID). |
event_type | agent.tool_call for tool calls. Other platform events written to the same chain use their own types. |
actor_type | The kind of identity that made the call, for example agent. |
actor_id | The identity that made the call. |
delegated_by | The person on whose behalf an agent acted, when the call was delegated. |
occurred_at | When the record was written. |
hash | SHA-256 of this record. See Hashing. |
previous_hash | The hash of your client’s previous record; 64 zeros for the first record in the chain. |
Each record also has a payload, which the MCP audit tools do not return today. The values of the payload fields that identify a person (actor_id, delegated_by, subject_user_id, requested_by, user_id, ip and user_agent) are encrypted with your client’s key; the rest of the payload is stored as plain JSON. If your client has no key yet, the payload is stored unencrypted.
| Payload field | Meaning |
|---|---|
tool | The MCP tool name. |
parameters | The parameters of the call, with sensitive fields redacted before storage. Some arguments, such as uploaded file contents, are stored only as a SHA-256 digest and a length. |
result_status | success, failed, denied, timeout, denied_not_configured or partial. |
scopes_used | The scopes on the calling token. |
lane, intent | How the platform classified the call, from its scopes and the tool. |
attestation_level | The attestation level recorded for the caller’s session. The platform records it but does not yet require it. |
session_id, session_id_source | The caller’s session and where that identifier came from. |
client_id, client_name, mcp_session_id, ip, user_agent | The MCP client application, its MCP session, and the network address and user agent of the call. |
via, surface, task_id, code_job_id, answered_from, duration_ms, error_class | Present when they apply: how the call was routed, the surface it came from, the task it served, the code job it ran, where an answer came from, how long it took and the class of any error. |
The payload can also carry fields the platform records for its own access-policy checks. The tool’s response is not stored, and inputs and outputs are not hashed separately.
Platform API change records
Each record has your client identifier and fields for the event category and type, the actor, the subject (type and identifier), the action, severity, a description, metadata, before and after state, IP address, user agent, session and correlation identifiers, the time it occurred, hash and previous_hash.
Hashing
hash = sha256( canonical_json(payload) + previous_hash )canonical_json is Python’s json.dumps(payload, sort_keys=True, default=str): keys sorted, default separators (", " and ": "), non-ASCII characters escaped. The concatenated string is UTF-8 encoded and the hash is lower-case hex. The first record of a chain uses 64 zeros as previous_hash.
- MCP tool-call records hash the plaintext payload above, before any field is encrypted. The
id,event_type,actor_type,actor_id,delegated_byandoccurred_atcolumns are stored next to the payload and are not covered by the hash. - Platform API change records hash these fields:
tenant_id,event_category,event_type,actor_type,actor_id,subject_type,subject_id,action,severity,description,metadata,before_state,after_state,ip_address,user_agent,session_idandcorrelation_id. The time and the hash fields themselves are not covered.
Checking a record
Three MCP tools read the MCP tool-call chain. Each needs the audit_events:read scope and is scoped automatically to your client.
| Tool | What it does |
|---|---|
audit_event_list | Lists records: id, event_type, actor_type, actor_id, delegated_by and occurred_at, with no hashes and no payload. Optional filters: event_type, since, until (ISO-8601), actor_id; limit defaults to 25, at most 200. |
audit_event_get | Returns one record’s columns, including hash and previous_hash. The payload is omitted. |
audit_event_hash_chain_verify | Verifies one record, given its event_id. |
Every record names the person who acted, so audit_event_list returns records only while your organization has per-person records switched on; otherwise the call is held. Filtering by another person’s actor_id needs an administrator.
audit_event_hash_chain_verify runs two checks:
- Structural. The record’s
previous_hashmatches thehashof an existing record of your client. Skipped for the first record. - Cryptographic. The platform decrypts the stored payload fields with your client’s key, recomputes the hash and compares it with the stored
hash.
| Result field | Meaning |
|---|---|
valid | true when the structural check passes and the recomputed hash matches (or the record has no payload). |
kind | cryptographic_rehash when the hash was recomputed, otherwise structural_link. |
is_genesis | Whether this is the first record of the chain. |
structural_valid | Result of the structural check. |
rehash_verified | Result of the cryptographic check; null when it could not run. |
computed_hash, stored_hash, previous_hash | The hashes compared. |
crypto_note | crypto_shredded when your client’s key has been destroyed, no_payload when there was nothing to hash. Present only in those cases. |
legacy_wrapper_form | true when the record verified under the one legacy hash form described in Current limits. Present only in that case. |
The result is not signed. If your client’s key has been destroyed after an erasure request, the hash can no longer be recomputed and the result is valid: false with crypto_note: "crypto_shredded".
Checking a range or the whole chain
MCP tool-call chain, daily. Every day at 02:40 UTC the platform walks your client’s whole MCP tool-call chain. It checks every link and recomputes each record’s hash where your client’s key allows; records it cannot recompute keep their link checked and are counted as unverifiable. Read the newest result with the get_audit_chain_status MCP tool (scope security:read) or GET /api/v1/security/audit-chain: whether the chain is intact, the time it is verified through, the rows checked and, if there is one, the first broken link with its reason.
Platform API change chain, over a time range. GET /api/v1/audit/events/verify?since=<ISO-8601>&until=<ISO-8601> checks every record in the range on the server. It checks links only and does not recompute hashes. It covers at most 50,000 records per request and answers 422 above that. The response gives status (ok or broken), rows_checked, the record and time it is verified through and, for a break, first_break_id and first_break_reason (hash_mismatch, fork or missing_predecessor).
Reading and exporting platform API change records
Platform API change records are read through GET /api/v1/audit/events (at most 100 per page) and checked through GET /api/v1/audit/events/verify. Both need the settings:admin scope, or a member with an unexpired Record read grant, which an administrator creates through POST /api/v1/audit/record-read-grants. The export, GET /api/v1/audit/events/export (CSV or JSON), needs settings:admin and is an Enterprise-tier capability. Neither the list nor the export returns hash or previous_hash today.
Append-only, and its one exception
Database triggers reject updates and deletes on the chained records. There is one sanctioned exception: an erasure request (for example under GDPR) briefly disables the trigger to clear the person’s identifier from delegated_by and actor_id on MCP records. Neither column is covered by the hash, so the chain still verifies afterwards.
Current limits
- Read-only platform API requests are not recorded.
- Recording an MCP call does not block most calls: if the write fails, the tool still returns and the failure is logged on the server, so a missing record is possible. A few write tools, such as saving a memory note or sending a message, refuse to complete when their record cannot be written.
- Platform API change records written before that chain was introduced have no hash and sit outside the chain.
- If a writer cannot read the previous hash, it starts again from 64 zeros. That shows up as a break when you verify, and in the daily check.
- Records of one historical event type were hashed in a different form (a wrapper around the payload) by a one-time backfill on 2 September 2026. The verifier accepts that form for that event type only and reports
legacy_wrapper_form: true. - Verification results are not signed, there is no offline verifier, and neither the list nor the export of platform API change records returns the hashes, so you cannot recompute those hashes yourself.
- The record format has no version marker yet. Changes to it will be noted on this page.
See the MCP reference for how to connect and discover tools.