> ## Documentation Index
> Fetch the complete documentation index at: https://platform.atlan.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the atlanai CLI; `atlanai --map json` prints its command map. Run a read-only identity check before any write.
> The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects.
> SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript.

# Track usage and audit tool calls

> See which agents called which tools, on which MCP servers, why, and with what outcome, across every server behind the gateway.

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.

<CardGroup cols={2}>
  <Card title="Session" icon="clipboard-list">
    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.
  </Card>

  <Card title="Tool call" icon="list">
    One row per call, ordered within its session. Holds the tool, the server,
    the rationale, the outcome, and the duration.
  </Card>
</CardGroup>

| 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. |

<Note>
  **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.
</Note>

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**.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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.

<Tabs>
  <Tab title="REST: count calls per day">
    Use [Aggregate artifacts of a kind](/api/references/api-reference) to
    build usage reports:

    ```bash theme={null}
    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.
  </Tab>

  <Tab title="MCP: read calls from an agent">
    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.
  </Tab>
</Tabs>

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.

## Next steps

<CardGroup cols={2}>
  <Card title="Connect a client" icon="plug" href="/gateway/mcp/how-tos/connect-a-client">
    Open a session and start recording calls.
  </Card>

  <Card title="Find and call tools" icon="magnifying-glass" href="/gateway/mcp/concepts/find-and-call-tools">
    Send the session and rationale fields on every call.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.