docs(mcp): document call timeouts, reconnect replay rules, and tool-loop limits

[slin1237]

Since the docs were ported, MCP tool execution gained:

• a per-call deadline (fix(mcp): bound tool calls and stop replaying non-idempotent calls on reconnect smg#2441);
• a rule that interrupted calls are never replayed unless the tool is idempotent (#2441);
• fail-closed pooled-connection lookup (#2091);
• tool-loop caps that are consistent across modes (#2665, #2674);
• a structured mcp_call.error (#2186).

Verifying these showed that the MCP pages described several features that do not take effect in v1.11.0:

• The config file. The gateway builds its MCP orchestrator from an empty config (app_context.rs:671-701), and startup only registers the servers list (workflow/job_queue.rs:642-675). So pool (including #2441's pool.call_timeout), policy, the top-level proxy, inventory, and warmup are read but never applied.
• SSE transport. SSE was removed with the rmcp bump (#1814), but the pages still documented it.
• Approval and audit. The pages presented approval policies and audit logging as working.

Changes

• concepts/extensibility/mcp.md (rewritten)
  • Where MCP runs: the Responses API on gRPC and ZMQ workers and on OpenAI-compatible providers, and the Messages API on the Anthropic backend with X-SMG-MCP: enabled (see docs(api): document Messages count_tokens and forwarded Anthropic headers #51). It does not run in Chat Completions.
  • Transports: stdio and streamable HTTP only, with the exact SSE error.
  • Static servers vs dynamic servers, and tool-name collision handling.
  • Tool-loop limits: max_tool_calls capped at 10, execution of the permitted prefix, no dispatch after length/failed/error finishes, and mixed MCP/client batches. A table covers how the Harmony, OpenAI-provider, and Messages paths differ.
  • Timeouts and failures: a fixed 120 s per-call deadline, and "outcome unknown" for interrupted calls. The replay path never fires today, because tool annotations are not loaded. Fail-closed pooled lookups, and the structured error shape.
  • Approval behavior as it actually works.
  • A config reference with an "Accepted but Not Applied" table.
  • Security notes, metrics, and troubleshooting.
  • Removed: invented pool latency numbers, and advice that contradicted the page.
• getting-started/mcp.md
  • Streamable HTTP and stdio examples, and a corrected dynamic-server example (no /sse, bare token).
  • server_label rules, plus limiting and filtering tools.
  • Corrected approval text, and a pointer to the Messages API.
• reference/mcp-internal-servers.md: exactly which paths hide internal server items (and which don't), plus the frontmatter it was missing.

Upstream issues found

These are worth smg issues; the docs describe current behavior:

• The MCP config's pool, policy, proxy, inventory, and warmup are never applied. The orchestrator is built from an empty config, and validate() never runs on the file.
• Static-server recovery looks servers up in that empty config, so a stdio server whose process exits never comes back.
• Server tool annotations are never loaded, so the #2441 idempotent-replay path never fires.
• The smg README and crates/mcp/README.md still advertise SSE, approval policies, and audit logging.

Verification

• Checked against smg v1.11.0 (3be823a7): crates/mcp (config, orchestrator, pool, session, approval), app_context.rs, workflow/job_queue.rs, and the Responses and Messages MCP loops on each path.
• pnpm lint, pnpm check (0 errors), and pnpm build pass.
• The link check is clean.
• All three pages render with status 200 under wrangler pages dev.

This is one of a series of docs PRs that bring the site up to smg v1.11.0, one per area.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

Next included review available in 16 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 4 included reviews currently available. Your 65 included PR review attempts over the past 7 days set your current allowance at 4 reviews per hour.

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: 0dbf08e3-2674-4e7a-b776-372b9f79ac4d

📥 Commits

Reviewing files that changed from the base of the PR and between 7362b40 and 2893f4e.

📒 Files selected for processing (3)

• src/lib/content/concepts/extensibility/mcp.md
• src/lib/content/getting-started/mcp.md
• src/lib/content/reference/mcp-internal-servers.md

---

_{Comment @coderabbitai help to get the list of available commands.}