Repository navigation
mcpx docs: level-2 configuration and modes content (first seven items) #4821
Description
Purpose
Write the remaining first seven content items in the mcpx level-2 manual: the "more normal set of docs" a new user can rely on after installation. This is the replacement for part 2 only of #1848, whose page-map part 1 merged as PR #2433. Per the 2026-11-03 ruling on tracker #1898, do not reopen #1848; this issue owns the remaining content.
Parent/order tracker: #1898. Map and fixed anchors: pkgs/mcpx/docs/level-2-page-map.md, items 53–59.
Scope
Write all seven mapped sections, verifying factual claims against current pkgs/mcpx main at implementation time:
configuration#common-config— config sources, search/discovery and load passes, precedence, and how to inspect effective values.configuration#server-config— server blocks, profiles/aliases, sharing and scope; distinguish config keymcpServersfrom CLI/API "servers".configuration#client-config— client/call-scoped settings and what a host configures to use mcpx; explain their distinct meanings.configuration#env-vars— setting variables versus host/harness/script context; use generateddocs/environment.md/ registry data rather than maintaining a competing variable list.modes#client-modes— socket, remote URL, autostart/spawn, and inline modes, with where scripts run and profile/output controls.modes#transport-options— upstream server transports versus downstream client transports; current HTTP/SSE/MCP behavior, listeners, and remote-access constraints.modes#server-modes— mcpx as an MCP server, upstream server sharing/scope, and daemon process modes; make the three meanings explicit.
Use the sources and per-item notes in the page map. In particular, do not reintroduce the obsolete mode config key or pooled value; document sharing/scope, the actual config search path, and the current legacy-SSE behavior. Keep generated facts generated: do not hand-copy tables owned by the settings registry, environment generator, parity table, OpenAPI document, or generated-reference work (#1843).
Acceptance
- The seven items have substantive, newcomer-readable content at the exact fixed anchors above; each explains practical choices and commands rather than only linking to the compendium.
- Existing source pages are reused where appropriate; update the level-2 page map's "Written by" references from closed mcpx docs: level-2 page map, and the configuration, modes and transport pages #1848 to this issue, and keep compendium navigation/manifest consistent with the resulting pages.
- Verify links and generated/reference content against current main. Resolve the map's relevant open questions in the docs or record a precise follow-up; do not silently publish contradictory facts.
- Run the targeted documentation checks, including
go test ./internal/settings ./internal/defaultsfrompkgs/mcpx, plusgit diff --check; report any unrelated baseline failure separately. - No code behavior changes or unrelated documentation areas are in scope.
Context
- Tracker: mcpx docs: level 2 -- the 'ok i just installed this thing what even is it' layer (tracker) #1898; level-2 map PR: docs(mcpx): level-2 page map — all 30 items mapped (#1848 part 1) #2433 (merged at
7d7851ddef77c96cfb1e6fda3c52b6c7342a9d79). - mcpx docs: level-2 page map, and the configuration, modes and transport pages #1848 is closed and remains closed by explicit ruling; this is its replacement child for the seven content sections only.
- Adjacent documentation issues are distinct: mcpx docs: interface pages -- abstract and client interfaces, CLI, MCP, binary, script, /v1 and the SDKs #1851 owns the interface/CLI/MCP/binary/scripts/API items; mcpx docs: plugin pages -- plugins, compatibility, interface and config, opencode v1 and v2, vibeMcp #1855 and mcpx docs: the FAQ, in the notes' own voice #1859 are closed.
Activity
dezren39 commentedon Nov 3, 2026
🤖 Agent note · filed and queued
dezren39 commentedon Nov 3, 2026
🤖 Agent note · picked up
Merge pull request #4851 from developing-today/queue/6919-4821-mcpx-l…
dezren39 commentedon Nov 3, 2026
🤖 Agent note · done — PR #4851 merged
dezren39 commentedon Nov 3, 2026
agent-note:v1 — correction (repo-worker-code, lane code-f)
This issue was briefly linked as a sub-issue of #1259 at 2026-11-03T09:46Z. That link was an error: fabricated tool output in my shift misreported the numbers of three issues I had just created for #1259, and I linked the wrong rows. The link has been removed (verified: this issue's only parent_issue_added event was that erroneous one, and it now has no parent). No other change to this issue was made by me. Apologies for the noise.