How do I record MCP and agent tool calls at the gateway with the scope grant each call ran under?

What should I check, step by step?

1. Put an MCP/HTTP gateway (or agent runtime hook that runs in your process, not in model-writable memory) on every tools/call path. Log before dispatch and after the result returns — including denials and timeouts.

2. For each call record: timestamp, agent/session/credential ids, MCP server URL or name + version, tool name, tool call id, argument hash (redact secrets; prefer SHA-256 of canonical JSON), result status/error type, and latency.
3. Bind the active grant on that same row: grant_id (or token jti), scopes or RFC 9396 authorization_details summary, audience/resource, expires_at, policy_version, and a check_revocation (or equivalent) result taken immediately before dispatch.
4. Store the trail in append-only storage the agent's tools cannot UPDATE or DELETE. Keep only opaque receipt ids in the chat/session JSON.
5. Correlate intent vs execution when you can: framework tool spans (OpenTelemetry execute_tool) are useful context; OS/kernel or sandbox telemetry catches side effects the agent never logged. Treat disagreement as a detection signal, not noise.
6. Fail closed when the grant is missing, expired, out of scope for the tool, or revoked mid-session — do not log-and-allow.
7. Alert when gateway logging stops or when call volume diverges sharply from agent-reported tool counts.
8. Hash-chain or checkpoint the trail head periodically (for example recorder_checkpoint / record_ai_run receipts) so later edits break a verifiable chain.

Why agent-written logs are not enough

An agent can omit, paraphrase, or rewrite its own tool history after a bad call. Sysdig reports cases where agent logs under-count processes and miss most credential-file reads the kernel observed — the log is useful context, not a sole audit source.

• The MCP tools specification asks clients to log tool usage for audit, show sensitive inputs, and keep a human able to deny invocations. That still lives next to the agent unless you also write from a gateway you control.
• How to log every AI agent tool call for audit covers hooks, OpenTelemetry fields, and hash chains inside the client. This page adds the outside-agent gateway and the grant columns on every row.

Bind each call to the grant that authorized it

A bare "tool X succeeded" line does not tell an auditor whether the call was in scope. Store grant_id, scopes/authorization_details, audience, and policy_version beside the tool name and argument hash.

• Re-read revocation and expiry at dispatch time (check_revocation / live token introspection), not only when the session started. A yes from this morning is not a warrant after revoke_agent_credential or an IdP revoke.
• precall_check before unfamiliar MCP servers gives listing, drift, and integrity signals; it does not replace the per-call grant binding on your gateway.
• When you need a signed summary of the run (model, prompt/output hashes, tool-call count), record_ai_run writes a ledger receipt verify_ai_run can check later — proof of what was recorded, not that every side effect was safe.

What can go wrong?

Logging only lives in the agent harness; after an incident the session JSON is the only copy and the agent (or a compromised host) can edit it.

• Gateway logs tool names but not grant_id or policy_version, so you cannot tell which authority covered a dangerous call.
• Revocation is checked at login once; short-lived access tokens and already-dispatched calls keep working until expiry while the trail still says "allowed".
• Argument bodies land in cleartext logs with tokens and PII; prefer hashes and redaction by default (OWASP logging guidance).