{
  "question": "How do I record MCP and agent tool calls at the gateway with the scope grant each call ran under?",
  "slug": "how-to-record-mcp-tool-calls-at-the-gateway-with-scope-grant-binding",
  "url": "https://www.rightshold.com/answers/how-to-record-mcp-tool-calls-at-the-gateway-with-scope-grant-binding",
  "short_answer": "Do not trust the agent's own tool log as the only evidence. Capture every tools/call (and comparable agent tool invocation) at a gateway or proxy the agent cannot edit, and bind each record to the scope grant that was in force for that call — grant id, scopes or authorization_details, credential/session id, policy version, and whether the grant was still unrevoked when the call started. Sysdig's AI Defense work shows why: in one study the kernel recorded about 2.6 million processes against roughly 374,000 tool calls in the agents' own logs, and most credential-file reads the kernel saw never appeared in the agent log. Gateway capture plus grant binding gives you what the agent meant to call and which authority it claimed, independent of whether the model later rewrites its session. Pair that with precall_check before unfamiliar tools and record_ai_run when you need a signed receipt of a run summary outside the session.",
  "checklist": [
    "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.",
    "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.",
    "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.",
    "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.",
    "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.",
    "Fail closed when the grant is missing, expired, out of scope for the tool, or revoked mid-session — do not log-and-allow.",
    "Alert when gateway logging stops or when call volume diverges sharply from agent-reported tool counts.",
    "Hash-chain or checkpoint the trail head periodically (for example recorder_checkpoint / record_ai_run receipts) so later edits break a verifiable chain."
  ],
  "sections": [
    {
      "heading": "Why agent-written logs are not enough",
      "points": [
        "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."
      ]
    },
    {
      "heading": "Bind each call to the grant that authorized it",
      "points": [
        "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."
      ]
    },
    {
      "heading": "What can go wrong",
      "points": [
        "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)."
      ]
    }
  ],
  "checks": [],
  "ask_rightshold": {
    "start": "https://www.rightshold.com/start?ref=seo",
    "mcp_endpoint": "https://www.rightshold.com/mcp",
    "ask": "Record a signed receipt for this agent run that hashes the prompt and output and notes the tool-call count from our gateway log.",
    "mcp_call": {
      "tool": "record_ai_run",
      "arguments": {
        "model": "provider/model@version",
        "provider": "example",
        "prompt_sha256": "<sha256 of prompt>",
        "output_sha256": "<sha256 of output summary>",
        "params": {
          "tool_calls": 17,
          "gateway": "mcp-gw-1",
          "grant_id": "grnt_…",
          "policy_version": 12
        },
        "ran_at": "2026-11-06T21:00:00-05:00"
      }
    },
    "also": [
      "Needs your API key. record_ai_run stores hashes and params you send, not raw prompts/outputs, and returns a signed ledger receipt; verify_ai_run is free.",
      "Call precall_check on unfamiliar MCP server URLs before the gateway allows tools/call to them.",
      "check_revocation (and revoke_agent_credential when you own the credential) so each gateway row can record whether the grant was live at dispatch.",
      "How to log every AI agent tool call for audit covers client hooks and OTel fields; How to re-check agent authority at execution time covers short-lived grants at the side-effect boundary."
    ],
    "scope": "Rightshold records signed AI-run receipts, pre-call checks and revocation lookups for agents that call it. It does not sit in your MCP gateway, capture kernel telemetry, or stop a client that never asks. Enforce gateway capture and grant binding in your proxy and runner too. Not legal advice."
  },
  "sources": [
    {
      "title": "Sysdig: Introducing Sysdig AI Defense (agent logs vs kernel execution evidence)",
      "url": "https://www.sysdig.com/blog/introducing-sysdig-ai-defense"
    },
    {
      "title": "Sysdig AI Defense platform (intent vs what actually ran)",
      "url": "https://www.sysdig.com/platform/ai-defense"
    },
    {
      "title": "Model Context Protocol specification (2025-11-25): Tools — security considerations (log tool usage)",
      "url": "https://modelcontextprotocol.io/specification/2025-11-25/server/tools"
    },
    {
      "title": "Model Context Protocol: Security best practices",
      "url": "https://modelcontextprotocol.io/docs/2025-11-25/tutorials/security/security_best_practices"
    },
    {
      "title": "OpenTelemetry GenAI semantic conventions: execute_tool spans",
      "url": "https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-spans.md"
    },
    {
      "title": "OWASP Logging Cheat Sheet",
      "url": "https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html"
    },
    {
      "title": "Verified AI Runs on Rightshold",
      "url": "https://www.rightshold.com/verified-ai-runs"
    }
  ],
  "related": [
    {
      "title": "How to log every AI agent tool call for audit",
      "url": "https://www.rightshold.com/answers/how-to-log-every-ai-agent-tool-call-for-audit"
    },
    {
      "title": "How to re-check agent authority at execution time",
      "url": "https://www.rightshold.com/answers/how-to-re-check-agent-authority-at-execution-time"
    },
    {
      "title": "How to keep an agent risk/approval record outside the agent's editable session",
      "url": "https://www.rightshold.com/answers/how-to-keep-an-agent-risk-approval-record-outside-the-agents-editable-session"
    },
    {
      "title": "How to revoke an AI agent's access immediately",
      "url": "https://www.rightshold.com/answers/how-to-revoke-an-ai-agents-access-immediately"
    }
  ],
  "computed_from": "Curated guidance; license verdicts computed from Rightshold's license profiles at render time. Not legal advice.",
  "updated": "2026-11-06"
}