Track usage and audit tool calls

Every call through Atlan MCP Gateway lands in one audit trail, whichever server answered it. You can see usage across all your MCP servers in one place, open any agent session to replay what it did, and pull the same records into your own reporting.

What the gateway records

The gateway records two things: the session an agent opens and each tool call made inside it. Calls to Atlan platform tools and calls to your registered servers are recorded the same way.

Session

Opened once per task with registry__initialise. Holds the agent’s stated objective, the client and version, the MCP protocol revision, and who opened it.

Tool call

One row per call, ordered within its session. Holds the tool, the server, the rationale, the outcome, and the duration.

Field on each tool call	What it tells you
`session_id`	The session the call belongs to. The gateway verifies it before the call runs.
`sequence_number`	The call’s position in its session, starting at 0.
`tool_name`	The tool that ran, without its namespace prefix.
`server_slug`	The server or platform surface that answered.
`rationale`	The agent’s own explanation of why it made the call.
`outcome`	`ok` if the tool answered, `error` if it did not.
`duration_ms`	How long the call took, measured at the gateway.
`error_class`	A coarse failure category for a failed call. It never contains the downstream response.
`protocol_version`	The MCP protocol revision the call used.
`traceparent`	The W3C trace context the client sent, which links the call to your agent’s trace.

Arguments and results are never stored. Tool inputs often carry credentials, customer records, or prompts, and outputs carry whatever the server returned. The audit trail records which tool ran, for whom, why, and how it ended. It does not record the data that passed through.

A session and its calls are create-only. Nobody can edit an audit record after it is written, including the agent that made the call.

See usage in the MCP Gateway studio

Open the MCP Gateway studio and choose a workspace, or All workspaces.

Check gateway health and volume on Overview

Overview shows Servers in service, Tools available, Tool calls · 7 days with the failure rate, and Sessions · 7 days. Below them are a Tool calls, last 14 days chart, the Most-called tools, Recent sessions, and a Needs attention list of servers that are disconnected or waiting for sign-in.

Review every call on Tool calls

Tool calls lists each call newest first, with When, Tool, Why, Outcome, Time, Session, and By. Filter by outcome (All, Failed, Succeeded) or by server to audit one MCP server across every agent that used it. The page shows the call count, failures, and the Median and p95 duration.

Replay one agent's work on Sessions

Sessions lists each session’s Objective, Client, Opened by, and Opened time. Open a session to read its calls in the order the agent made them.

Answer common audit questions

Question	Where to look
How much is the gateway used, and is that growing?	Overview: 14-day call chart and 7-day totals
Which tools do agents rely on most?	Overview: Most-called tools
What did agents do on a specific MCP server?	Tool calls, filtered by that server
Why did an agent call a write tool?	Tool calls: the Why column
Which calls failed, and where?	Tool calls, filtered to Failed
What did one agent do, step by step?	Sessions: open the session
Which server is slow?	Tool calls: Median and p95 for a server filter

Query the audit trail programmatically

Sessions and calls are Registry artifacts of kind mcp_session and mcp_session_message, so you can read them with the same tools and APIs as any other artifact.

REST: count calls per day
MCP: read calls from an agent

Use Aggregate artifacts of a kind to build usage reports:

curl -X POST "https://api.atlan.com/registry/v1/aggregate/mcp_session_message" \
  -H "Authorization: Bearer $ATLAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "<workspace-id>",
    "filters": [{ "field": "created_at", "op": "gte", "value": "2026-10-01T00:00:00Z" }],
    "group_by": [{ "field": "created_at", "bucket": "day" }],
    "metrics": [{ "op": "count" }],
    "sort": ["created_at"]
  }'

Each result group holds one day and its call count. Aggregates group by shared artifact fields such as created_at. To break calls down by server_slug, tool_name, or outcome, read the call rows.

An agent connected to the gateway can read the trail through Registry tools. Call registry__list_artifacts with kind set to mcp_session_message to browse recent calls, or with mcp_session to browse sessions.The caller sees only the sessions and calls its workspace permissions allow.

To follow a call into your agent’s own trace, have the client send a W3C traceparent in the request’s _meta. The gateway stores it on the call and passes it on to the downstream server.

Who can see the audit trail

Sessions and calls follow workspace access. People and agents can read the records in workspaces they can read. A session opened by a person lives in the account’s root workspace.

Limits

Recording is best-effort. If a record cannot be written, the tool call still succeeds, and that call is missing from the trail.
Calls are recorded only when made inside a verified session. The gateway refuses a call with no session_id, except registry__initialise.
The trail does not include tool arguments or tool output.

AI Gateway

MCP Gateway

What the gateway records

Session

Tool call

See usage in the MCP Gateway studio

Answer common audit questions

Query the audit trail programmatically

Who can see the audit trail

Limits

Next steps

Connect a client

Find and call tools

​What the gateway records

Session

Tool call

​See usage in the MCP Gateway studio

​Answer common audit questions

​Query the audit trail programmatically

​Who can see the audit trail

​Limits

​Next steps

Connect a client

Find and call tools

What the gateway records

See usage in the MCP Gateway studio

Answer common audit questions

Query the audit trail programmatically

Who can see the audit trail

Limits

Next steps