docs(workflows): say what to check when MCP tools don't load

[hercemer42]

Follow-up to PRD-876. The executor half (agent-nodejs#1806) makes Forest Runtime name why an MCP connector failed to load its tools; this documents what a reader does with that.

Forest Runtime → Observability

New subsection, "When an MCP step can't load its tools": the Error line as it appears at the default log level, and what each failure kind implies for the fix — auth reconnect the credential, connection unreachable or past the 15s per-server timeout, unknown read the error text. Also states that a server answering with no tools is an empty list rather than an error, which is the behaviour the PR changes.

The LOG_LEVEL row in Tuning now says what Debug buys you (per-server tool count and load time), since "Debug, Info, Warn, or Error" gave no reason to ever lower it.

MCP Connectors

New "A connector's tools don't load" section. The page previously ended at "Check that all the expected tools are exposed" with no guidance when they aren't. It now names the three failure modes in the order worth checking — nothing published, credential rejected, server unreachable — and points self-hosters at the runtime logs that distinguish them.

Nothing removed; no existing statement was inaccurate.

Note

Document MCP tool loading failures and empty tool list behavior in workflow docs

• Adds a new subsection in forest-runtime.mdx explaining what to check when an MCP step can't load its tools, including a JSON log example and a breakdown of kind values (auth, connection, unknown).
• Clarifies that a server returning no tools is not a connection failure — it results in an empty tool list and is a server configuration issue.
• Notes in mcp-servers.mdx that an empty tools list in step 4 means the server responded but published no tools.
• Documents that setting LOG_LEVEL to Debug adds one line per MCP server with its tool count and load time.

^{Macroscope summarized d4a9ab2.}

[linear-code]

PRD-876

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
forest	🟢 Ready	View Preview	Aug 7, 2026, 7:27 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[macroscopeapp]

🟡 Medium workflows/forest-runtime.mdx:247

The documented JSON example shows a failures array with server, kind, and error fields, but the actual production log emits requestedMcpServerId, mcpServerName, and failedConfigNames — not failures. The kind field does not exist in the log, so operators following the guidance to use kind to distinguish auth, connection, and unknown failures cannot find it. Update the example to match the real payload, or change the logging to include the kind field.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @product/process/workflows/forest-runtime.mdx around line 247:

The documented JSON example shows a `failures` array with `server`, `kind`, and `error` fields, but the actual production log emits `requestedMcpServerId`, `mcpServerName`, and `failedConfigNames` — not `failures`. The `kind` field does not exist in the log, so operators following the guidance to use `kind` to distinguish `auth`, `connection`, and `unknown` failures cannot find it. Update the example to match the real payload, or change the logging to include the `kind` field.