Log Tools

MCP tools for inspecting runtime logs. Two independent sets are covered here:

• Instance logs (logs_*) — B2C Commerce instance logs read over WebDAV. Supports one-shot fetch and buffered tailing.
• MRT logs (mrt_logs_*) — Managed Runtime application logs streamed over a WebSocket. Watch-only (live stream, no historical fetch).

Instance log tools are available in the CARTRIDGES, DIAGNOSTICS, and SCAPI toolsets. MRT log tools are available in the DIAGNOSTICS, PWAV3, and STOREFRONTNEXT toolsets.

---

Instance logs

Inspect logs on a B2C Commerce instance via WebDAV — investigate errors after triggering a request, monitor a job run, or audit recent failures.

Authentication

Tools that read from the instance (logs_list_files, logs_get_recent, logs_watch_start) require WebDAV-capable credentials.

Required:

• Basic Auth preferred: hostname, username, and password (WebDAV access key) for a Business Manager user with WebDAV log read permission.
• OAuth (client-credentials / implicit) is also supported as a fallback for WebDAV.

Configuration priority: Flags → Environment variables → dw.json config file

logs_watch_poll, logs_watch_stop, and logs_watch_list operate on server-side state only and do not require fresh credentials per call.

See Configuration for credential setup.

logs_list_files

List log files on the instance via WebDAV.

Parameter	Type	Required	Default	Description
prefixes	string[]	No	all	Filter by log prefix (e.g., ["error", "customerror"]). A path-like value such as "internal/server" lists logs in a subdirectory.
sort_by	"date" | "name" | "size"	No	date	Sort field
sort_order	"asc" | "desc"	No	desc	Sort order

Returns: {count, files: [{name, prefix, size, lastModified, path}]}.

logs_get_recent

Fetch recent log entries in a single request/response. Filters (since, level, search) are applied client-side after fetching.

Parameter	Type	Required	Default	Description
prefixes	string[]	No	["error", "customerror"]	Log prefixes to read. A path-like value such as "internal/server" reads logs from a subdirectory.
count	number	No	50	Maximum entries to return
since	string	No		Relative time ("5m", "1h", "2d") or ISO 8601
level	string[]	No		Filter by level (ERROR, WARN, INFO, DEBUG, FATAL, TRACE)
search	string	No		Case-insensitive substring filter

Returns: {count, entries: [{file, level, timestamp, message, raw}]}.

logs_watch_start

Start a background log watch. Returns a watch_id immediately. Buffers entries in memory until logs_watch_poll drains them.

Workflow: call logs_watch_start before triggering the action that should produce logs. Otherwise startup may emit only existing entries (controlled by last_entries) and miss what you wanted to capture.

Parameter	Type	Required	Default	Description
prefixes	string[]	No	["error", "customerror"]	Log prefixes to watch. A path-like value such as "internal/server" watches logs in a subdirectory.
last_entries	number	No	0	Pre-existing entries per file to emit on startup. 0 (default) captures only new entries; set >0 for recent context.
poll_interval_ms	number	No	3000	How often the underlying tail polls WebDAV
level	string[]	No		Drop entries not matching level before buffering
search	string	No		Drop entries not matching substring before buffering

Returns: {watch_id, hostname, prefixes, started_at}.

logs_watch_poll

Drain buffered entries. If the buffer is empty, blocks up to timeout_ms waiting for new entries.

Parameter	Type	Required	Default	Description
watch_id	string	Yes		Watch id from logs_watch_start
timeout_ms	number	No	5000	Max time to block when buffer is empty. 0 returns immediately.
max_entries	number	No	200	Maximum entries returned per call

Returns: {watch_id, entries, files_discovered, files_rotated, errors, truncated, buffered_remaining, dropped_entries, stopped}. When truncated is true, call again to drain the rest.

• entries: [{file, level, timestamp, message, raw}] — buffered since the last poll.
• files_discovered / files_rotated: [{name, prefix, size, lastModified, path}] — each file is reported once, on the poll after it is discovered/rotated.
• errors: [{message, at}] where at is an ISO 8601 timestamp of when the tail error occurred.
• dropped_entries: count of entries evicted (buffer cap) since the last poll; resets to 0 after each poll.

logs_watch_stop

Stop a watch and release its underlying tail.

Parameter	Type	Required	Description
watch_id	string	Yes	Watch id from logs_watch_start

Returns: {watch_id, stopped_at, total_entries_seen}.

logs_watch_list

List active watches. Use to recover orphaned watches or inspect buffered counts.

No parameters.

Returns: {watches: [{watch_id, hostname, prefixes, buffered_entries, total_entries_seen, dropped_entries, files_discovered, stopped, created_at, last_activity_at}]}.

Recovering orphaned watches: watches live in the MCP server process and only one is allowed per hostname. Call logs_watch_list to find a lost watch, then logs_watch_stop with its watch_id. Idle watches are destroyed after 30 minutes; restarting the MCP server clears all watch state.

---

MRT logs

Tail real-time application logs from a Managed Runtime (MRT) environment over a WebSocket — watch SSR/server output while reproducing a request, verifying a deployment, or investigating an error on PWA Kit and Storefront Next storefronts.

MRT logs are always a live stream: there is no historical fetch and no log files to list. The workflow is watch-only — start a watch, drain it with poll, then stop.

Authentication

All MRT log tools require MRT API authentication (the same credentials as mrt_bundle_push).

Required:

• MRT API key — from --api-key, the MRT_API_KEY environment variable, or ~/.mobify.
• Project — from --project / -p, MRT_PROJECT, or mrtProject in dw.json.
• Environment — from --environment / -e, MRT_ENVIRONMENT, or mrtEnvironment in dw.json.

Optional:

• Cloud origin — from --cloud-origin, MRT_CLOUD_ORIGIN, or mrtOrigin in dw.json (defaults to https://cloud.mobify.com).

mrt_logs_watch_poll, mrt_logs_watch_stop, and mrt_logs_watch_list operate on server-side state only and do not require fresh credentials per call.

See Configuration for credential setup.

mrt_logs_watch_start

Start a background tail of the configured MRT environment's logs. Returns a watch_id immediately and buffers entries in memory until mrt_logs_watch_poll drains them. Project and environment are taken from configuration, not tool parameters.

Workflow: call mrt_logs_watch_start before triggering the request or SSR action you want to capture. Because MRT logs are a live stream, anything emitted before the watch connects is not captured.

Parameter	Type	Required	Default	Description
level	string[]	No		Drop entries not matching these levels (ERROR, WARN, INFO, DEBUG, ...) before buffering. Case-insensitive.
search	string	No		Drop entries not matching this case-insensitive substring (against message and raw) before buffering.

Returns: {watch_id, project, environment, started_at}.

The CLI b2c mrt tail-logs --search treats the pattern as a regex; this MCP tool uses a simpler, safer case-insensitive substring match for search.

mrt_logs_watch_poll

Drain buffered entries. If the buffer is empty, blocks up to timeout_ms waiting for new entries. Returns immediately if entries are already buffered or the stream has stopped.

Parameter	Type	Required	Default	Description
watch_id	string	Yes		Watch id from mrt_logs_watch_start
timeout_ms	number	No	5000	Max time to block when buffer is empty. 0 returns immediately.
max_entries	number	No	200	Maximum entries returned per call

Returns: {watch_id, entries, errors, truncated, buffered_remaining, dropped_entries, stopped}. When truncated is true, call again to drain the rest.

• entries: [{timestamp, requestId, shortRequestId, level, message, raw}] — parsed MRT log entries buffered since the last poll. requestId/level/timestamp are present when the line can be parsed; message and raw are always present.
• errors: [{message, at}] where at is an ISO 8601 timestamp of when the WebSocket error occurred.
• dropped_entries: count of entries evicted (buffer cap) since the last poll; resets to 0 after each poll.
• stopped: true once the WebSocket has closed — whether via mrt_logs_watch_stop, an idle/server timeout, or a connection failure. When stopped is true, check errors for the reason and start a new watch to resume.

mrt_logs_watch_stop

Stop a watch and close its WebSocket. Idempotent — stopping an already-stopped watch returns success.

Parameter	Type	Required	Description
watch_id	string	Yes	Watch id from mrt_logs_watch_start

Returns: {watch_id, stopped_at, total_entries_seen}.

mrt_logs_watch_list

List active watches. Use to recover orphaned watches or inspect buffered counts.

No parameters.

Returns: {watches: [{watch_id, project, environment, origin, buffered_entries, total_entries_seen, dropped_entries, stopped, created_at, last_activity_at}]}.

Recovering orphaned watches: watches live in the MCP server process and only one is allowed per project/environment/origin. Call mrt_logs_watch_list to find a lost watch, then mrt_logs_watch_stop with its watch_id. Idle watches are destroyed after 30 minutes; restarting the MCP server clears all watch state.

---

See also

• Logs CLI commands — b2c logs tail / get / list
• MRT CLI commands — b2c mrt tail-logs and the rest of the b2c mrt command tree
• mrt_bundle_push — build and deploy MRT bundles
• Script Debugger — step through server-side code with breakpoints