Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hercemer42 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2c05da7
docs(workflows): say what to check when MCP tools don't load
hercemer42 Aug 7, 2026
d4a9ab2
docs(mcp-servers): fold the empty-tool-list meaning into setup
hercemer42 Aug 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion get-started/connect/integrations/mcp-servers.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ If a tool isn't in the list above, connect any MCP server by URL:
"apiKey": "your-api-key"
}
```
4. Check that all the expected tools are exposed.
4. Check that all the expected tools are exposed. An empty list means the server answered but published nothing — a configuration problem on the server, not a connection failure.
5. Save your configuration.

Learn more about building and hosting MCP servers in the [Claude MCP documentation](https://docs.claude.com/en/docs/agents-and-tools/remote-mcp-servers).
25 changes: 24 additions & 1 deletion product/process/workflows/forest-runtime.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -239,6 +239,29 @@ If your workflows include [MCP Tasks](/product/process/workflows/overview) backe

The Docker image ships with [OpenTelemetry](https://opentelemetry.io/) APM built in, compatible with any OTLP backend (Datadog, Grafana Tempo, Jaeger, Honeycomb…). It is **off by default** and turns on as soon as you set `OTEL_EXPORTER_OTLP_ENDPOINT`. OpenTelemetry is bundled only in the Docker image, not the npm package.

### When an MCP step can't load its tools

Forest Runtime logs the reason at `Error`, so it is in your logs without changing `LOG_LEVEL`:

```json
{

@macroscopeapp macroscopeapp Bot Aug 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

"level": "Error",
"message": "MCP servers failed to load tools",
"mcpServerName": "acme-crm",
"failures": [
{ "server": "acme-crm", "kind": "connection", "error": "connect ECONNREFUSED 10.0.4.12:8080" }
]
}
```

`kind` tells you where to look:

- `auth` — the server rejected the credential. Reconnect the connector, or renew its token.
- `connection` — unreachable, refused, or slower than the 15-second per-server load timeout.
- `unknown` — the server answered but the load failed anyway; `error` carries the reason.

A server that answers but exposes no tools is not a failure: you get an empty tool list and no error.

## Tuning

Beyond the required variables, these optional knobs have sensible defaults and rarely need changing:
Expand All @@ -247,7 +270,7 @@ Beyond the required variables, these optional knobs have sensible defaults and r
| --- | --- | --- |
| `HTTP_PORT` | `3400` | Port Forest Runtime's HTTP server listens on. |
| `POLLING_INTERVAL_S` | `30` | How often it polls the orchestrator for pending steps. |
| `LOG_LEVEL` | `Info` | `Debug`, `Info`, `Warn`, or `Error`. |
| `LOG_LEVEL` | `Info` | `Debug`, `Info`, `Warn`, or `Error`. `Debug` adds one line per MCP server with its tool count and load time. |
| `STEP_TIMEOUT_S` | `300` | Max duration of a single step. |
| `AI_INVOKE_TIMEOUT_S` | `30` | Max duration of a single AI provider invocation. |
| `STOP_TIMEOUT_S` | `30` | Grace period on shutdown to finish in-flight steps before exiting. |
Expand Down