docs: add dedicated MCP tool reference page

[dgageot]

Every toolset type in docker-agent has its own reference page under docs/tools/<name>/ and a sidebar entry under "Built-in Tools" — except MCP, which is arguably the most-used toolset. Users browsing the docs sidebar had no obvious entry point and had to know to look under Configuration → Tool Config.

This change adds a dedicated MCP reference page at docs/tools/mcp/index.md that covers all three MCP flavours (Docker MCP via ref: docker:<name>, local stdio with command/args/env, and remote SSE / Streamable HTTP), the reusable top-level mcps: block, and common options like tool filtering, deferred loading, instruction, toon, per-toolset model routing, and lifecycle. A new "MCP" entry is added to the sidebar (between OpenAPI and A2A), and a one-line cross-reference links from the existing ## MCP Tools section in the configuration guide.

Validated locally with task lint (0 issues) and task test (all packages green). A schema mismatch in a YAML example was caught and fixed during review (command is a string, not an array; arguments belong in args).

[docker-agent]

Assessment: 🟡 NEEDS ATTENTION

One documentation inaccuracy found in the new MCP reference page.

[docker-agent]

[MEDIUM] Documentation example uses openai/gpt-5-mini — likely a non-existent model name

The "Reusable Definitions" example uses model: openai/gpt-5-mini, but gpt-5-mini is not a publicly available OpenAI model. The same PR uses openai/gpt-4o-mini in the per-toolset model routing example (line 197), which is likely the intended model here as well.

While gpt-5-mini is registered in the codebase's internal model recogniser (modelinfo_test.go), it is not publicly available on OpenAI's API, so users copy-pasting this example will get an error. Consider replacing with openai/gpt-4o-mini (or another real available model) to keep the documentation example immediately runnable.

[docker-agent]

Assessment: 🟡 NEEDS ATTENTION

One confirmed documentation bug in the new MCP reference page: a YAML example uses a non-existent OpenAI model name ( instead of ). All other reviewed findings were dismissed (the remote.oauth field is schema-backed and correctly added, nav placement is appropriate for the existing site structure).

[docker-agent]

[MEDIUM] Incorrect model name openai/gpt-5-mini — should be openai/gpt-4o-mini

The Reusable Definitions YAML example uses model: openai/gpt-5-mini, but gpt-5-mini is not a real OpenAI model. The correct name for OpenAI's small/efficient model is gpt-4o-mini.

This is inconsistent with the rest of the file: line 197 of this same new page already uses the correct openai/gpt-4o-mini, and the existing authoritative reference at docs/configuration/tools/index.md (line 326) also uses openai/gpt-4o-mini as the canonical example.

Readers who copy-paste this example will get a runtime error when the agent tries to use the non-existent model.

Suggested fix:

  root:
    model: openai/gpt-4o-mini

[aheritier]

Well-structured page that fills a genuine gap in the docs. All CI checks pass, internal cross-references are valid, and the schema descriptions are accurate (the new page even improves on the existing configuration/tools/ page by correctly separating command from args). Approving with two should-fix items and five low-priority suggestions.

---

🟡 Should fix

1. Lifecycle intro excludes Docker MCP (inaccurate)

The lifecycle block applies to all three MCP flavours, including ref: docker:*. The intro sentence "Local stdio and remote MCP servers are supervised…" is misleading — readers with Docker MCP entries will think lifecycle supervision does not apply to them. The existing configuration/tools/ reference is more accurate on this point.

Suggested fix: "All MCP toolsets (Docker, stdio, and remote) are supervised: crashed servers reconnect automatically…"

2. docker-agent in prose (STYLE.md violation)

Two callouts on this page use docker-agent as a product name in prose. Per STYLE.md:

"Talking about the product? → 'Docker Agent'
Showing a command the user types? → docker agent run agent.yaml"

Both occurrences should read Docker Agent (not docker-agent).

---

🔵 Low-priority suggestions

3. allow_private_ips: false in the remote example is the default

Explicitly showing allow_private_ips: false alongside the comment # Optional is confusing — it's the default value, so there's no reason to set it. The existing configuration/tools/ page shows allow_private_ips: true (i.e. the override case). Recommend removing this line or switching to true to illustrate when you'd actually want to set it.

4. remote.oauth sub-fields not enumerated

The property table lists remote.oauth as object with a link to the feature page. Readers who just want a quick field reminder would benefit from a one-liner: accepts clientId, clientSecret, callbackPort, scopes, callbackRedirectURL. The delegation to the feature page is acceptable design, but a parenthetical list here would save a round-trip.

5. openai/gpt-5-mini in the Reusable Definitions example

Per STYLE.md, the canonical example model is anthropic/claude-sonnet-4-5 unless the example is specifically about that model. The mid-page snippet under ## Reusable Definitions (mcps:) uses openai/gpt-5-mini; this is inconsistent with the Combined Example at the bottom (which correctly uses anthropic/claude-sonnet-4-5).

6. Missing defer property table

The "Deferred loading" section shows YAML examples but no property table, unlike every other sub-section in Common Options. A small table (defer | true or array[string] | description) would maintain consistency.

7. Docker MCP Catalog URL inconsistency (pre-existing, not caused by this PR)

This page correctly uses https://hub.docker.com/u/mcp. The existing configuration/tools/index.md uses https://hub.docker.com/search?q=&type=mcp. The new page is aligned with the canonical URL — no change needed here; configuration/tools/ is the outlier.

---

Positive notes:

• Schema accuracy is good — command correctly typed as string, not an array.
• Nav placement (between OpenAPI and A2A) is correct.
• All {{ relative_url }} anchors resolve correctly.
• The cross-reference added to configuration/tools/index.md is minimal and well-placed.
• Combined Example at the bottom uses the correct anthropic/claude-sonnet-4-5.

[aheritier]

🟡 Should fix: Lifecycle supervision applies to all three MCP flavours, not just stdio and remote. The lifecycle: examples on this very page already show ref: docker:duckduckgo with a lifecycle profile.

Suggested replacement:

All MCP toolsets (Docker, stdio, and remote) are supervised: crashed servers reconnect automatically with exponential backoff.

[aheritier]

🟡 Should fix (STYLE.md): docker-agent is a command/binary name. When referring to the product in prose, use Docker Agent.

docker-agent opens your browser → Docker Agent opens your browser

[aheritier]

🟡 Should fix (STYLE.md): Same product-name violation as in the Remote MCP section. docker-agent in prose should be Docker Agent.

docker-agent looks it up → Docker Agent looks it up

[aheritier]

🔵 Suggestion: allow_private_ips: false is the default value. Showing it explicitly alongside # Optional is confusing — why would a reader set an option to its default? The existing configuration/tools/ page shows allow_private_ips: true (the meaningful override case). Recommend removing this line or changing it to true.

[aheritier]

🔵 Suggestion: The remote.oauth entry is correct to delegate to the feature page. A brief parenthetical listing the accepted sub-fields (clientId, clientSecret, callbackPort, scopes, callbackRedirectURL) would save readers a round-trip for a quick reminder.

[aheritier]

🔵 Suggestion (STYLE.md): The canonical example model per STYLE.md is anthropic/claude-sonnet-4-5. openai/gpt-5-mini here is not illustrating a model-specific feature. The Combined Example at the bottom of this page already uses the correct canonical model — this mid-page snippet should match.