> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcpmanager.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Viewing Logs
> Where to find MCP request logs in MCP Manager, what every log column and log type means, how the four-entry correlation model works, where to view logs scoped to a server, gateway, connection, or app, and how to export them.
MCP Manager records every request and response that passes through your MCP gateways and makes them available as **logs**. Logs exist in two kinds of places: a central **Logs** page that shows activity across the entire workspace, and scoped views attached to individual servers, gateways, connections, and apps. Think of the central page as the headquarters and the scoped views as satellites that show the same data filtered to one entity.
If you don't see a **Logs** link in your left-hand navigation — or a **Logging** tab on a server, gateway, connection, or app — your role doesn't have the **View and export logs** capability. Viewing and exporting logs in every location described here is controlled by that capability. See [Who can view and export logs](#who-can-view-and-export-logs).
## Where to find logs
Open the **Logs** link in the left-hand navigation at [Logs](https://app.mcpmanager.ai/settings/logging/logs). The Logs page is organized into three tabs:
* **Logs** — the workspace-wide table of recent MCP request and response activity. This is the main view and the focus of this page.
* **Export History** — a record of the log exports generated in your workspace, with their status and a link to download each finished file.
* **Integrations** — where you configure forwarding of logs downstream to an OpenTelemetry-compatible collector.
The **Integrations** tab is where you connect MCP Manager to an OpenTelemetry-compatible collector so that logs can be forwarded into your SIEM or observability stack. That is covered separately in [Export to SIEM](/enterprise/export-to-siem); this page focuses on viewing and exporting logs inside MCP Manager.
## The logs table
When you open the **Logs** tab you immediately see a table of the most recent log activity across all connections in the workspace, newest first. Each row is a single log entry — one leg of a message's journey through the gateway, not a whole request/response exchange (see [Log types and the correlation model](#log-types-and-the-correlation-model)).
In this first version the logs are presented as a **flat tabular dataset**: every entry is its own row, and related entries are tied together by a shared correlation ID rather than being visually grouped into spans or traces. You can sort and filter the table by its columns to narrow down what you are looking at.
## Log types and the correlation model
Every log entry has a **type** that identifies which leg of a message's journey it represents. A single MCP message travels four legs through the gateway, so one message generally produces **four log entries that share the same `correlation_id`**:
```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'fontFamily':'Lato, sans-serif','actorBkg':'#aed8ff','actorBorder':'#0b4880','actorTextColor':'#062b4c','signalColor':'#6a6b76','signalTextColor':'#12141d','noteBkgColor':'#fff8e4','noteBorderColor':'#ffa535','noteTextColor':'#12141d'}}}%%
sequenceDiagram
participant Client as 🤖 MCP Client
participant Gateway as 🛡️ MCP Gateway
participant Server as 🖥️ MCP Server
Client->>Gateway: 1. proxy_request_success
Gateway->>Server: 2. mcp_request_success
Server->>Gateway: 3. mcp_response_success
Gateway->>Client: 4. proxy_response_success
```
1. The client's request arrives at the gateway — `proxy_request_success`.
2. The gateway forwards the request down to the MCP server — `mcp_request_success`.
3. The MCP server's response returns to the gateway — `mcp_response_success`.
4. The gateway returns the response to the client — `proxy_response_success`.
Because each leg is logged independently, you can follow a single message end-to-end by filtering on its `correlation_id` and reading the four entries in order. For a hands-on walkthrough, see [Trace a tool call in your logs](/tutorials/trace-in-logs).
### Type values
Each leg has a success and an error variant, and additional types are recorded when policy enforcement or gateway feature filtering acts on a message.
| Type | Meaning |
| ------------------------------------------------- | ------------------------------------------------------------- |
| `proxy_request_success` / `proxy_request_error` | The client's request arriving at the gateway. |
| `proxy_response_success` / `proxy_response_error` | The gateway's response being returned to the client. |
| `mcp_request_success` / `mcp_request_error` | The gateway's request being sent to the MCP server. |
| `mcp_response_success` / `mcp_response_error` | The MCP server's response being received by the gateway. |
| `policy_enforced_abort` | A policy blocked the message. |
| `policy_enforced_mutation` | A policy modified the message. |
| `gateway_feature_blocked` | A gateway rule blocked a feature (tool, prompt, or resource). |
| `gateway_feature_filtered` | A gateway rule filtered a feature out of the response. |
The four `*_success` types — `proxy_request_success`, `mcp_request_success`, `mcp_response_success`, and `proxy_response_success` — are the ones you will see most often, one per leg, for a healthy message.
### Trace and span IDs
Alongside the `correlation_id`, every log entry carries OpenTelemetry **trace identifiers** that tie the legs of a request together and let a log pivot to a distributed trace. MCP Manager mints these for **every** proxied request, whether or not a traces collector is configured — see [Traces and trace-correlated logs](/enterprise/export-to-siem#traces-and-trace-correlated-logs).
* **`trace_id`** — the same value on all of a request's legs (like `correlation_id`, but the W3C trace ID your observability backend understands). Filter on it to gather every log in one trace.
* **`span_id`** — the span that entry represents. The client- and server-facing legs carry the **gateway span**; each **rule-engine** evaluation carries its own distinct child span, so a rule engine's log entry can be matched to its span in a trace waterfall.
* **`traceparent`** — the W3C `traceparent` on that leg. On the client-facing `proxy_request_success` leg it is **present only when the client sent one**: its presence means the trace was *received* from the client, and its absence means MCP Manager *minted* the trace itself. The server-facing `mcp_*` legs always carry the `traceparent` forwarded upstream.
You can filter the table by `trace_id` and `span_id`; `traceparent` is shown on an entry but is not a filter column.
## What each log column means
Each log entry carries a wide set of columns. Most are self-explanatory; the ones below are worth a note. You can sort by any column, and several columns can be used to filter the table.
* **`created_at`** — the timestamp the entry was recorded, with microsecond resolution. The table is sorted by this, newest first, by default.
* **`type`** — the leg of the journey, as described in [Log types and the correlation model](#log-types-and-the-correlation-model).
* **`method`** — the JSON-RPC method the message carried, such as `tools/call`, `prompts/get`, or `resources/read`.
* **`correlation_id`** — the identifier shared by the (typically four) entries that belong to one message. Use it to reconstruct a full exchange.
* **`trace_id`**, **`span_id`**, and **`traceparent`** — the OpenTelemetry trace identifiers for the entry, described in [Trace and span IDs](#trace-and-span-ids). `trace_id` is shared across all legs of a request; `span_id` identifies that leg's span; `traceparent` records the W3C trace context on the leg, and signals whether the trace was received from the client or minted by MCP Manager. `trace_id` and `span_id` are filterable.
* **`request_id`** and **`session_id`** — the JSON-RPC request identifier and the MCP session identifier. These are populated only when the relevant value is available for that entry, so they are filled in sparsely depending on the log type.
* **`response_code`** and **`response_type`** — the HTTP status code and content type (for example `application/json` or `text/event-stream`) on response-leg entries.
* **`duration_ms`** — how long the leg took, in milliseconds.
* **`headers`** and **`body`** — the full headers and body of the message, captured when they are available for that entry.
* **`token_count`** and **`tokenizer_encoding`** — an estimate of the message size in tokens, and the encoding used to produce it (see the note below).
* **`feature_type`** and **`feature_name`** — the kind of MCP feature involved (such as a tool, prompt, or resource) and its specific name, populated when a feature operation is being logged.
* **`json_rpc_version`** and **`mcp_protocol_version`** — the JSON-RPC version (typically `2.0`) and the negotiated MCP protocol version.
* **`rule_engine_id`**, **`rule_engine_type`**, and **`rule_engine_comment`** — populated only on entries produced by a rule engine, recording which engine acted, how it classified the message (for example `pass`, `modify`, or `block`), and any comment it returned.
### Names and identifiers for each entity
For each entity involved in a message, a log entry stores both a human-readable **name** in plain text and a globally unique **identifier (GUID)**. The plain-text name makes the table easy to read; the GUID is the precise, stable value used for sorting and filtering so that you can scope a view to exactly one entity. The entities recorded this way include:
* **Outbound gateway** — `outbound_gateway_name` and `outbound_gateway_guid`.
* **Host** — `host_name` and `host_guid`.
* **Inbound server** — `inbound_server_name`, `inbound_server_url`, and `inbound_server_guid`.
* **Inbound server identity** — `inbound_server_identity_name` and `inbound_server_identity_guid`.
* **Server container** — `server_container_name` and `server_container_guid`.
* **Connection** — `gateway_connection_guid`.
* **User** — `user_name`, `user_email`, and `user_guid` (plus the originating `ip_address`).
* **Organization and team** — `org_guid` and `team_guid`.
Additional GUID columns capture the precise configuration in effect for the message, including `gateway_assignment_guid`, `feature_lists_snapshot_guid`, `feature_list_guid`, and `feature_item_guid`.
Because not every column applies to every type of entry, columns such as `request_id`, `session_id`, the identity columns, and the rule-engine columns are filled in sparsely — populated only when that piece of information is meaningful for the given log entry.
The token estimate is informational guidance, not an exact measurement. MCP Manager estimates the size of each message using a single tokenizer (the `o200k_base` encoding) so that you get a consistent, approximate sense of message length in tokens. This may not match the tokenizer your specific LLM uses, so treat `token_count` as an approximation rather than a precise figure.
Every column available on a log entry:
* `created_at` — timestamp the entry was recorded (microsecond resolution).
* `type` — which leg of the journey the entry represents.
* `method` — JSON-RPC method (for example `tools/call`).
* `correlation_id` — identifier shared across the entries of one message.
* `trace_id` — W3C trace ID, shared across all legs of one request.
* `span_id` — the span this entry represents (gateway, upstream, or rule-engine leg).
* `traceparent` — W3C trace context on this leg; absent on the client-facing leg when MCP Manager minted the trace rather than receiving it.
* `request_id` — JSON-RPC request identifier.
* `session_id` — MCP session identifier.
* `response_code` — HTTP status code.
* `response_type` — response content type.
* `duration_ms` — leg duration in milliseconds.
* `headers` — message headers, when available.
* `body` — message body, when available.
* `token_count` — estimated token size of the message.
* `tokenizer_encoding` — encoding used for the estimate.
* `outbound_gateway_name` / `outbound_gateway_guid` — the outbound gateway.
* `host_name` / `host_guid` — the host.
* `inbound_server_name` / `inbound_server_url` / `inbound_server_guid` — the inbound server.
* `inbound_server_identity_name` / `inbound_server_identity_guid` — the inbound server identity.
* `server_container_name` / `server_container_guid` — the server container.
* `gateway_connection_guid` — the connection.
* `gateway_assignment_guid` — the gateway assignment in effect.
* `feature_lists_snapshot_guid` / `feature_list_guid` / `feature_item_guid` — the feature configuration in effect.
* `user_name` / `user_email` / `user_guid` — the acting user.
* `ip_address` — originating IP address.
* `org_guid` / `team_guid` — organization and team.
* `feature_type` / `feature_name` — the MCP feature involved.
* `json_rpc_version` — JSON-RPC version.
* `mcp_protocol_version` — negotiated MCP protocol version.
* `rule_engine_id` / `rule_engine_type` / `rule_engine_comment` — rule-engine outcome details.
## Opening a single log entry
Click any row in the logs table to open the **log detail view** for that entry. The detail view shows the entry's key fields together — including its type, method, timestamp, token count, duration, response code, the outbound gateway and inbound server names, the user, the feature involved, and the **trace, span, and traceparent** values — and then renders the full **body** and **headers** of the message when they are available, formatted for readability. Use this when the table row alone does not give you enough context to understand what happened.
## Pagination
The logs table is paginated. You can change how many entries load at a time, choosing between **50, 100, or 250 entries per page**; the default page size is **50**. Your selected page size is remembered for the next time you open the table.
## Exporting logs
The logs table includes an **Export** action that generates a downloadable file of your logs. When you export, you choose:
* **Format** — export as **CSV** (the default) or as **ND-JSON** (newline-delimited JSON), depending on how you intend to process the data downstream. CSV opens directly in spreadsheet tools; ND-JSON is easier to stream and parse record by record in a data pipeline.
* **Time range** — the span of logs to include. The range you can select is bounded by your plan's log retention period: logs older than that window are not available to export (see [How long logs and exports stay available](#how-long-logs-and-exports-stay-available)).
Before the export runs, MCP Manager shows you an **estimated file size and row count** so you know roughly how large the file will be. The estimate updates as you switch format, because ND-JSON repeats field names on every row and so runs somewhat larger than the equivalent CSV.
For large exports, prefer **ND-JSON**. When an export is estimated at more than **100,000 rows**, MCP Manager suggests ND-JSON, which streams and parses more efficiently at that scale than a single large CSV. Very large exports — roughly **5 GB or more** — are flagged before you start, since they take longer to generate and to download.
### How an export runs
Generating the file is **asynchronous** — MCP Manager builds it in the background rather than blocking the page, so you can navigate away and come back later.
Choose your format and time range and start the export. MCP Manager queues the job and begins generating the file in the background.
When the file is finished, MCP Manager sends an email to the address on your account. For security, the email does **not** contain the file or a public download link — it contains a link that opens MCP Manager, so only someone signed in to your workspace can retrieve the data.
Following the link signs you in and opens your [Export History](#export-history), where the download for that export starts automatically. You can also open Export History at any time to download a file you requested earlier — you do not have to wait for the email.
### Export limits
To keep exports responsive for everyone in your workspace, MCP Manager caps how many can run at once:
* **Per person** — you can have up to **3 exports generating at the same time**. If you start another while three are still in progress, MCP Manager asks you to wait for one to finish and try again.
* **Per workspace** — your workspace can start up to **25 exports per day**. The count resets at **00:00 UTC** each day, rather than on a rolling 24-hour basis, so a workspace that hits the limit can export again after the next reset.
These limits govern how many exports you can *start* at a time; they do not limit how much data a single export can contain.
Exporting is available on **every MCP Manager plan**. Your plan changes only how far back you can export — the [log retention period](#how-long-logs-and-exports-stay-available) — not whether export is available at all. Who can run an export within your workspace is a separate question, controlled by the **View and export logs** capability (see [Who can view and export logs](#who-can-view-and-export-logs)).
Exports generated from the workspace-wide **Logs** tab are labeled to include the term **"all logs"**, which distinguishes them from exports generated in a scoped location. Exports from a [scoped view](#scoped-log-views) are labeled with that scope — for example the MCP server or gateway they came from — so you can tell at a glance which slice of data a file contains.
## Export History
The **Export History** tab lists the log exports generated in your workspace, newest first. Use it to download a file you requested earlier, to check whether an export you triggered has finished, or to start a fresh copy of a previous export.
Each entry shows its **status**, the **format** (CSV or ND-JSON), the **row count** and **file size**, when it was **created** (in UTC), and who **requested** it. The status is one of:
| Status | What it means |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ready** | The file finished generating and can be downloaded. |
| **Running** | The export is still being generated in the background. |
| **Expired** | The download window has passed (see [How long logs and exports stay available](#how-long-logs-and-exports-stay-available)). Re-run the export to generate a fresh file. |
| **Failed** | The export did not complete. Re-run it, or open the error detail for more information. |
| **Cancelled** | The export was cancelled before it finished. |
Each row offers the relevant actions for its status — **Download** for a ready file, and **Re-run** to generate a new copy with the same format, time range, and filters. When you arrive from the link in an export-ready email, the matching entry's download starts automatically.
## How long logs and exports stay available
Two separate time windows govern log availability, and it helps to keep them distinct.
* **Log retention period** — how far back your stored logs go, and therefore the maximum age of a log you can view or export. This period is set at the **organization level** by your plan — it applies across your whole workspace, not per gateway — and starts at **14 days**, extending to **a year or more** at higher plan levels. **Retention periods longer than 12 months can be configured**, subject to your plan and agreement with your MCP Manager contact. To find the plan that fits the retention you need, speak with your MCP Manager contact. For example, if your plan's retention period is 30 days, you can export logs up to 30 days old; a log that is 31 days or older falls outside the window and cannot be exported.
* **Download availability window** — how long a *generated export file* stays downloadable after MCP Manager creates it. Every export's download link is valid for **7 days** from the moment the file finishes generating; after that the link expires and the file is removed from our servers. This window is fixed — it does not vary by plan — and applies to the export file, not to the underlying log data.
The two windows are independent. The **log retention period** depends on your plan and determines how much history you can reach. The **download availability window** is a fixed **7 days** and determines how long a finished export file stays downloadable. If a link has expired, re-run the export from [Export History](#export-history) to generate a fresh file and a new 7-day window.
If you need to keep logs for longer than your plan's retention period — including indefinitely, for compliance — forward them to your own OpenTelemetry-compatible collector and store them there for any duration you choose. The retention period above governs only the copy held inside MCP Manager. See [Export to SIEM](/enterprise/export-to-siem).
## Scoped log views
Beyond the workspace-wide Logs page, MCP Manager makes logs available directly on the entities they relate to. Each scoped view shows the same columns as the global table but is filtered to the single entity you are looking at, and each offers its own scoped export. The scoped locations are:
Open [MCP Servers](https://app.mcpmanager.ai/settings/servers) in the left-hand navigation, select a server, and open its **Logging** tab. You see only the log entries whose server matches the MCP server you are viewing.
Open [Gateways](https://app.mcpmanager.ai/settings/gateways) in the left-hand navigation, select a gateway, and open its **Logging** tab to see the log entries scoped to that gateway.
From a gateway, open its **Connections** tab and click a connection in the label and connection-ID column to open that connection's detail page, which includes a logs table and export. A connection is the intersection of a specific gateway, a specific MCP client, and a specific user, which makes it the narrowest log scope MCP Manager offers.
Open the [Apps & Agents](https://app.mcpmanager.ai/settings/hosts) list, select an app or agent, and open its **Logging** tab to see the log entries for connections involving that app or agent.
Each scoped export is automatically restricted to that entity, which is a convenient way to pull just the logs for one server, gateway, connection, or app.
## Who can view and export logs
Access to logs is controlled by capabilities. Under the **Capabilities** tab when managing a role (in [People](https://app.mcpmanager.ai/settings/people)), the **Logging** group contains two capabilities:
| Capability | What it allows |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **View and export logs** | View and export logs in every location described on this page — the workspace-wide Logs page and all scoped views. |
| **Manage OpenTelemetry collector** | Configure, edit, and remove the OpenTelemetry collector used to forward logs downstream. |
**View and export logs** is what grants a person the ability to see logs at all: when a user's role has it, the **Logs** nav link and the per-entity **Logging** tabs are available to them; when their role does not, those links and tabs are hidden. Capabilities are assigned per role and are fully configurable — including on any custom roles you create — so access depends on the capabilities granted to a person's role, not on any fixed role name. Because log contents can include sensitive request and response data, grant **View and export logs** only to the roles that should see it.
**Manage OpenTelemetry collector** additionally lets a person set up and maintain the downstream log-forwarding integration described in [Export to SIEM](/enterprise/export-to-siem).
## Accessing log data programmatically
MCP Manager does not offer an API to pull or query logs — there is no endpoint to fetch logs programmatically, for example by session ID. To work with log data outside the MCP Manager interface, you have two options:
* **Export a file** — generate a CSV or ND-JSON file from the [Export](#exporting-logs) action and process it downstream.
* **Forward logs over OpenTelemetry** — stream logs to your own OpenTelemetry-compatible collector, then store and query them in your own observability platform or SIEM. See [Export to SIEM](/enterprise/export-to-siem).
## Logs and Reporting
Logs are the underlying data source for the **Reporting** section. The charts you see under [Reporting](/features/reporting) — such as feature call volume over time and feature popularity — are built from the activity captured in your logs. If you need the raw, per-message detail behind a chart, the logs are where to find it.
## Logs versus Alerts
Logs and [Alerts](/features/alerts) are related but serve different purposes. Logs capture every individual request and response that flows through the gateway, at full per-message detail. Alerts surface higher-level events to administrators — for example errors, or the outcomes of rule engines configured on specific gateways — that may warrant attention. Reach for logs when you need to trace exactly what happened on a given message; reach for alerts when you want to be notified about notable events across the workspace.
## Further reading
Keep customer PII out of AI by filtering it inline before it reaches the model.
The dashboards built live from the log data described here.
Forward logs to your own OpenTelemetry collector for long-term retention.
Higher-level events surfaced to administrators, alongside per-message logs.