Audit Logs

A record of everything that happens in your organization, from sign-ins and configuration changes to every MCP call

Introduction

To get these records into Splunk, Falcon LogScale, Elastic or Sentinel, see the guide How to get audit logs of every MCP tool call into your SIEM.

Gatana keeps an audit log of everything that happens in your organization:

  • every MCP request, including each tool call
  • every sign-in
  • every change to a resource: servers, credentials, profiles, teams, skills, artifacts, secret stores, and organization settings

Each record names the identity behind the event: the user, the profiles that were active, and the credential the call came through, whether an OAuth client or a personal access token. This lets you answer "what did this client do?" even when several clients act as the same user.

Open Audit Logs in the left sidebar to read the log. Organization owners see all records; everyone else sees their own activity.

Logging Detail

How much an MCP call records is set by the MCP audit log level in your organization settings:

LevelWhat a call records
offMCP calls are not recorded
terse (default)The server, the tool, the duration, and who called it
detailedAdds the call arguments
detailed-with-errorAdds the response of failed calls
verboseAdds the response of every call

Sign-ins and resource changes are always recorded, whatever the level.

Omit MCP Protocol Messages is On by default in the organization settings. It excludes initialize, server/discover, ping, tools/list, notifications/* and subscriptions/* from the log. Turn this setting off to log these messages too. Note that at the verbose loging level, each tools/list record includes the full tool list which sometimes can we very large.

Outcome of a Call

Every tool call record (tools/call) carries an outcome, at every level including terse. It says how the call ended in one word, so a filter or a SIEM rule can find the calls that matter without reading the response. Records of protocol messages, such as initialize and tools/list, have no outcome:

outcomeMeaning
okThe tool ran and returned a result
deniedGatana refused the call because a policy said no. reason names the policy
not-foundThe name matched no server or tool the caller could see. Disabled servers and tools count as not found
needs-credentialsThe policy allowed the call, but no credential exists yet for this user, profile or server
credentials-rejectedThe provider no longer accepted the stored login, for example because it was revoked or expired. The user or an administrator must authorize the server again
upstream-errorThe tool ran and reported an error, or the server could not be reached
invalid-argumentsGatana checked the arguments against the tool's schema and they did not match. The tool did not run. Only calls from the web app are checked this way
failedThe call did not complete for another reason: an internal failure, a firewall rule that could not be evaluated, or a connection that closed early
unauthenticatedThe request carried no usable credential and never reached a tool

A denied record also carries a reason:

reasonWhich policy refused the call
server-accessThe server is not shared with the user or any of their teams
server-scopeThe token is limited to certain servers, and this server is not one of them
profile-toolThe profiles bound to the caller exclude this tool
read-onlyThe token may only read, and the tool does not declare itself read-only
firewallA firewall rule of the server denied the call. The rule's own firewall_deny event names the condition that matched
protection-check-argumentsA protection found a match in the arguments, such as a secret, and its action is Block. The tool did not run
protection-checkA protection found a match in the result and its action is Block. Gatana withheld the result. Only this denial reason means the tool ran and may have changed data

isError keeps its own meaning: the tool ran and failed, or the connection broke. A denied call is outcome: "denied" with isError: false, because Gatana answered the client with an error of its own rather than running the tool. To see every call that Gatana stopped, filter on Outcome is denied.

A record with outcome: "ok" and isSocketError: true means that the tool ran and returned a result, but the connection closed before the client received all of it. The outcome stays ok because the tool did its work: if it changed data, that change happened.

Code mode is covered too. Code that runs in the sandbox can only call the tools its caller may see; a name outside that set fails inside the sandbox and never reaches a tool. Gatana still records each such name as a tool call of its own, with mode: "codemode" and an outcome of denied (with the reason) or not-found, under the same user and credential as the execute_code call that ran the code. So a script that reaches for a tool its caller was not given leaves the same trace as a direct call would, even when the script catches the error.

Filtering

The list opens on the last 7 days. Use the date control for other ranges. Add filter builds a condition from a field, a comparison, and a value. The comparisons are is, is not, and contains. Date fields use is after and is before.

You can filter by event name, resource type, outcome, denial reason, protection, protection action, user, OAuth client, access token, server, tool, profile, team, credential, and secret store. Select known values from a list, or enter a value. is not matches only records that have the field. For example, Outcome is not ok returns tool calls with an outcome other than ok. It excludes records without an outcome.

A record must match all conditions. Filters stay in the page URL, so you can bookmark or share a view.

Protection and Protection action filter the protection matches of a tool call. They support only is and is not. Protection is Secrets returns calls with a secrets match. Protection is not Secrets returns calls where another protection matched and the secrets check did not. Both exclude calls without protection matches.

Conditions can match different protections in the same call. For example, Protection is Personal data with Protection action is Block also returns a call where Secrets blocked and Personal data only audited.

The same conditions work on the audit log endpoints of the public API, as a repeated query parameter of the form filter=field:operator:value:

GET /api/v1/audit-logs?filter=clientId:eq:CLIENT_ID&filter=toolName:contains:search

The fields are eventName, entityType, entityId, userId, date, clientId, patId, serverSlug, toolName, outcome, reason, protectionCheck, protectionAction, profileId, teamId, credentialId, and secretStoreId. protectionCheck takes secrets, pii and injection. protectionAction takes audit, redact and block. For example, filter=protectionCheck:eq:secrets returns the calls with a secrets match.

Each list record contains summary fields in details, such as toolName, outcome, and reason. These show what was called, who called, and the result. To read arguments, responses, or the previous and new resource values, get the record by ID:

GET /api/v1/audit-logs/RECORD_ID

To export complete records in bulk, use SIEM streaming.

Retention

Gatana Cloud keeps audit records for 365 days. Nightly cleanup removes older records. To keep records longer, use SIEM streaming.

Self-hosted installs keep records for 180 days by default. Set auditLogs.maxAgeDays to change the period, or to 0 to keep all records. See On-Premise & Self-Hosting.

Streaming to Your SIEM

To push audit events to a security platform you control, with your own retention, dashboards, and detection rules, see SIEM Streaming.

Last updated on

On this page