Skip to content

mcpx docs: the FAQ, in the notes' own voice #1859

New issue
New issue
Closed
#2454
Closed
mcpx docs: the FAQ, in the notes' own voice#1859
#2454
Assignees
dezren39
Labels
queue/queuedHas a queued task in the Supabase agent queuestatus:done

Description

@dezren39
dezren39
opened on Oct 28, 2026

Relocated from dezren39/darwin-nix#149 on 2026-10-28 (placement audit): mcpx's single source lives in developing-today/code (pkgs/mcpx); re-home tracked at #309. Original body below; issue references inside it are historical (dezren39/nix numbering).

Parent: #94

Summary

The notes end the level-2 list with five questions, written in the voice of a skeptical first-time reader. They become the FAQ. Each line is a heading word for word, including the quotes, the , no. and the .., and each gets a short, candid answer in the same voice, based on facts in the repo.

Proposed placement: one level-2 page, faq, with a fixed anchor per question (listed in #146's page map). The home page's "now what" (#157) and the home page itself (#155) link to it. The pages each question touches also link back to it: "is it safe?" from scripts#script, the code-mode question from the opencode plugin pages (#148).

Original notes

Source-notes lines 1, 2, 7, 49-52 (parents) and 78-82 (this issue). The lines in between are quoted in sibling issues.

  • documentation
    • make a book using whatever is the most common and simple modern choice
      • 3 main things, not book sections jsut like levels of detail-
        • the 'ok i just installed this thing what even is it' layer
          • basically a more normal set of docs
          • new person might assume this is all there is and wont be upset
          • a page or section in a page for
            • "so why'd you get rid of all the mcp and then make one, do you like mcp or not"
            • "i mean, opencodemode is right there"
            • "is it safe?", no.
            • "but why would you.."
            • "but can i get some examples?"

Current state (what mcpx does today, with file refs)

There is no FAQ. The material for the answers exists but is spread across files:

  • story.md "# Summary" and "mcpx speaks MCP"
  • OPENCODE-V2.md, and its 2026-09-29 correction block
  • docs/opencode-plugin.md §1
  • AGENTS.md "Scripts"
  • internal/runner/runner.go:41-66
  • ASSESSMENT.md
  • the story.md opening walk
  • manual.go Examples fields, and mcpx recipes

Paths are relative to pkgs/mcpx/ on main (d0b7e01; re-checked at 05c78b2 on 2026-09-30, with no drift in the cited lines). Every command cited below is in Commands(), except mcpx serve (dispatched but not listed; see #147 Finding 1).

One trap: OPENCODE-V2.md's body predates its own correction. Its side-by-side table ("TypeScript is rejected") and its "If you stay on opencode v1 ... none of v2's Code Mode is available to you today" are both wrong according to the correction block and docs/opencode-plugin.md §1. The FAQ must use the corrected facts.

Approaches: where the FAQ lives

  • A (least recommended): no FAQ page; scatter the questions as callouts on the relevant pages. This loses the thing that makes these five lines valuable: they are the questions everyone asks first, in the order they ask them, in a voice that admits the obvious objection. A reader who wonders "is it safe?" should not have to guess that the answer sits on the scripts page.
  • B (middle): put the FAQ in the compendium next to the comparisons and history (Phase 0: baseline, toolchain, dependencies, and small fixes #153). The long answers do live there. But lines 50-51 say a new person may assume level 2 is all there is. Those readers are exactly the ones asking these questions, and they would never find the answers.
  • C (recommended): a level-2 faq page, one anchor per question. Each answer is at most about 120 words and ends with one "more" link into level 2, or into the compendium (Phase 0: baseline, toolchain, dependencies, and small fixes #153) for history. It is linked from home's "now what" and from the pages above. The agent twin (Update module github.com/jackc/pgx/v5 to v5.9.2 [SECURITY] #120) carries it as a single file, which suits llms.txt. The short answers keep it at level 2, and the links give the long form to anyone who wants it.

Answer direction per question

These are drafts of tone and content, not final copy. They are candid, short, and they admit weaknesses where they exist.

"so why'd you get rid of all the mcp and then make one, do you like mcp or not"

Anchor faq#do-you-like-mcp.

We like MCP fine. mcpx didn't get rid of it. It got rid of tool schemas in the model's context:

  • "mcpx puts every MCP server behind one command so their schemas stay out of the model's context until something asks for them" (story.md "# Summary").
  • Underneath, mcpx is an MCP client of every server you configure, across four protocol revisions (docs/protocol.md §1). It reads the same mcpServers config every other host reads.
  • It is also an MCP server itself: /mcp on the daemon, mcpx serve --transport stdio.

The one it "made" is deliberately tiny, because "Exposing three hundred tools over MCP would rebuild the problem mcpx was built to solve, with extra steps" (story.md "mcpx speaks MCP"). mcpx_exec is the tool that matters.

More: mcp#mcp (#147).

"i mean, opencodemode is right there"

Anchor faq#opencode-code-mode.

It is, and not only in v2. opencode v1 ships code mode behind OPENCODE_EXPERIMENTAL_CODE_MODE, it is on by default in v2, and both accept TypeScript (OPENCODE-V2.md corrections; docs/opencode-plugin.md §1).

Where opencode's is better, said plainly:

  • Confinement. Its purpose-built interpreter runs "only the language features we implement", which is a stronger security posture than any permission flag mcpx has.
  • OAuth and elicitation for remote servers.

(mcpx has since copied its budgeted catalog, catalog diffs and in-script search().)

What mcpx does that it does not:

  1. It works outside a model turn. A shell script, CI, cron or a different harness can call it. There is "no opencode2 exec".
  2. One daemon serves every harness, with real per-session processes for stateful servers. opencode keeps "one MCP connection per server per location", so two sessions share one Chrome.
  3. Scripts run on a real runtime with imports and a filesystem.

The recommendation in OPENCODE-V2.md still holds: let code mode own ordinary MCP for opencode's own loop, and use mcpx for stateful servers and for everything outside a turn.

More: #153.

"is it safe?", no.

Anchor faq#is-it-safe.

The answer starts with "No."

  • Scripts run on a real runtime with your full authority: "filesystem, network, subprocesses" (AGENTS.md "Scripts").
  • script.permissions defaults to all (--allow-all on Deno). The narrower profiles (net, read, read-net, strict) apply only on Deno: "bun and node run with the user's own authority whatever is asked" (internal/runner/runner.go:41-49).
  • The daemon API is unauthenticated. It listens on loopback and on a socket only you can open, and binding wider prints a warning (story.md "One daemon, many clients").
  • mcpx prompt hands a generated script back instead of running it, "because generated code runs with your credentials".

What this means for the reader:

  • Treat a script like a shell command you are about to paste.
  • Configure only servers you would run by hand.
  • Do not expose the port.

That is the whole answer. This issue does not design security (see the footer).

"but why would you.."

Anchor faq#why.

Three reasons, then the history:

  1. Context cost. Tool schemas sit in every request, whether or not the tools get used. mcpx's always-on cost is zero (OPENCODE-V2.md side-by-side). In the opening walk, "There are 27 Chrome tools live on this machine and not one byte of their schemas is in the agent's context".
  2. Stateful servers under concurrency. Two agents sharing one browser corrupt each other. mcpx leases a process per session (story.md "Sharing and scope").
  3. Reach. The same tools from a shell, CI or any harness.

History: this replaced lootbox, which the user was maintaining as a fork 51 commits ahead of a quiet upstream. Discovery there was uncached (about 650 ms per request), and "an architecture that cannot express the one thing you actually need (more than one Chrome)" (ASSESSMENT.md "Summary").

More: #153.

"but can i get some examples?"

Anchor faq#examples.

Yes. The answer is short and points at an examples gallery, which is where the real work of this item lies. Material that exists today:

  • the story.md opening walk (a real prompt, one script, two screenshots, with exact bytes);
  • mcpx recipes (saved scripts with // @param holes);
  • named scripts in .mcpx/scripts/;
  • the per-command Examples in internal/cli/manual.go;
  • the snippets in AGENTS.md and docs/exec.md.

Approaches for the gallery:

Open questions

  1. Voice. Should the answers use "we", "I" (as OPENCODE-V2.md and ASSESSMENT.md do), or no pronoun? The notes are first person and casual.
  2. Scope of "but why would you..". Does it mean "why would you use this over plain MCP / code mode" (drafted above), or "why would you build it", which is the history? The draft covers both briefly.
  3. Examples. Should the gallery be a sibling page (examples) that the FAQ links to? Or should it stay as a section of the FAQ until there are more than a handful of examples?
  4. Correcting OPENCODE-V2.md. Should its stale body be corrected in place, not just prefaced by the correction block, before the FAQ links to it? Phase 0: baseline, toolchain, dependencies, and small fixes #153 owns the comparison pages.

Ease · Impact · Related

Ease S for the FAQ page; the examples gallery under C is M and depends on the testing CI · Impact med-high: these five answers decide whether a skeptical first-time reader stays · Depends on / related: #94, #47, #49, #52 (closed, fixed in #182), #155, #156, #157, #146, #147, #148, #153, #120

Security/auth deferred; see tracker.

Activity

  1. developing-today commented on Oct 28, 2026

    @developing-today
    developing-todayBot
    on Oct 28, 2026 – with developing.today
    Contributor

    CODE-786

  2. dezren39 commented on Oct 28, 2026

    @dezren39
    dezren39
    on Oct 28, 2026
    MemberAuthor

    History carried over from dezren39/darwin-nix#149 (verbatim, oldest first):

    @dezren39 · 2026-09-30T07:20:31Z

    Integration pass. Placed in the DAG rooted at #181.

    @dezren39 · 2026-09-30T12:01:28Z

    Issues pass (2026-09-30, at 05c78b2). This was a small factual edit. The answers, the approaches and the gallery plan are unchanged.

  3. dezren39
    added
    queue/queuedHas a queued task in the Supabase agent queue
    status/needs-triageNot yet triaged; needs a first look
    on Oct 28, 2026
  4. github-actions
    assigned
    dezren39
    on Oct 28, 2026
  5. dezren39
    added
    work/assignedQueue worker lifecycle state
    queue/claimedQueue worker lifecycle state
    status/in-progressQueue worker lifecycle state
    and removed
    status/needs-triageNot yet triaged; needs a first look
    queue/queuedHas a queued task in the Supabase agent queue
    on Oct 29, 2026

  6. dezren39 commented on Oct 29, 2026

    @dezren39
    dezren39
    on Oct 29, 2026
    MemberAuthor

    🤖 Agent note · picked up

  7. dezren39 commented on Oct 29, 2026

    @dezren39
    dezren39
    on Oct 29, 2026
    MemberAuthor

    🤖 Agent note · triage verdict — CONFIRMED, no duplicate, follow-up enqueued

    Verdict: CONFIRMED. No FAQ exists; the issue's Approach C stands (a level-2 faq page, one anchor per question, plus the runnable-examples gallery); its open questions are settled or routed below. Follow-up enqueued.

    Verified fresh at current main 82b019a0 (2026-10-29):

    1. No FAQ page. pkgs/mcpx/docs/ tree checked — no faq page. The answer material exists where the issue says it does: docs/story.md, OPENCODE-V2.md (with its correction block), ASSESSMENT.md, AGENTS.md "Scripts", docs/opencode-plugin.md §1, all present at pkgs/mcpx/ on main. One drift note for the writer: the internal/runner/runner.go:41-66 citation has moved (that range is now client-workdir code) — the permissions substance ("profiles apply only on Deno; bun/node run with the user's authority") is stated in AGENTS.md "Scripts" as the issue also cites; cite that, or re-locate the runner lines at write time.
    2. Dedupe — no duplicate. mcpx docs: the FAQ, in the notes' own voice #1859 is the only code issue scoped to the FAQ (docs searches surface it as the FAQ item; mcpx docs: level 2 -- the 'ok i just installed this thing what even is it' layer (tracker) #1898 is its level-2 tracker parent, mcpx docs: a runnable, editable example on the home page (WASM vs hosted daemon vs local) #1876/mcpx docs: overview, quick start, install page and 'now what' #1878/mcpx docs: plugin pages -- plugins, compatibility, interface and config, opencode v1 and v2, vibeMcp #1855 are sibling page sets). Nothing to close.
    3. Open questions, settled or routed:
      • Voice (Q1): settle as "we", first person, casual — that is what the issue's own drafted answers use ("We like MCP fine"), it matches the notes' voice the page exists to preserve, and it avoids the single-author "I" of the design docs. Not worth Drew's time as a separate decision; if he dislikes it, it is a one-pass copy edit.
      • "but why would you.." scope (Q2): the draft already covers both readings briefly (use-over-MCP/code-mode first, history second) — keep that shape.
      • Examples placement (Q3): sibling examples page + examples/ directory of runnable scripts (Approach C), linked from faq#examples — a section of the FAQ cannot be CI-executed, and CI execution is the entire point of C. The FAQ answer itself stays short and points at the gallery.
      • Correcting OPENCODE-V2.md in place (Q4): not this issue's work — comparisons are the compendium tracker's ground (see mcpx docs: comparisons (lootbox, opencode code mode, Cloudflare Code Mode, ...) and the project's history #1869). The FAQ follow-up must simply never rely on the stale body: use the correction block and docs/opencode-plugin.md §1 facts, as the issue's trap note demands.
    4. Non-negotiables carried into the follow-up intact: the five headings verbatim (quotes, ", no." and ".." included); fixed anchors (faq#do-you-like-mcp, faq#opencode-code-mode, faq#is-it-safe, faq#why, faq#examples); each answer ≈120 words max, candid, ending with one "more" link; "is it safe?" starts with "No." and designs no security; examples run in CI against deterministic servers (testsupport fixture or pinned filesystem server on a temp dir — not live Chrome), reusing the e2e daemon-hygiene pattern (MCPX_STATE_DIR isolation, idle-exit, mcpx stop --all cleanup).

    Follow-up: implementation packet enqueued to repo-health-code-pilot (task ID in the completion note) covering the FAQ page and the runnable examples gallery as one docs delivery.

  8. dezren39 commented on Oct 29, 2026

    @dezren39
    dezren39
    on Oct 29, 2026
    MemberAuthor

    🤖 Agent note · triage complete

    • Agent: queue worker (repo-worker-code), Lane D shift
    • Session / ID: queue task 2747 → follow-up task 3069
    • Outcome: Triage CONFIRMED (verdict above). Implementation follow-up enqueued to repo-health-code-pilot as task 3069 (small_fix, dedupe_key repo-health:v1:fix:developing-today/code:issue:1859); this issue now carries queue/queued for it.
  9. dezren39
    removed
    status/in-progressQueue worker lifecycle state
    queue/claimedQueue worker lifecycle state
    on Oct 29, 2026

  10. 12 remaining items

  11. dezren39
    added
    user/reviewNeeds a user-look: Muse reviews first and handles what it can
    and removed
    user/reviewNeeds a user-look: Muse reviews first and handles what it can
    on Oct 29, 2026

  12. dezren39 commented on Oct 29, 2026

    @dezren39
    dezren39
    on Oct 29, 2026
    MemberAuthor

    🤖 Agent note · PR opened, parked for CI

    • Agent: queue worker (repo-worker-code), OpenChamber scheduled lane
    • Session / ID: queue task 3069
    • Task: implement mcpx docs: the FAQ, in the notes' own voice #1859 — level-2 faq page + runnable examples gallery
    • Artifact: PR docs(mcpx): the FAQ and a runnable examples gallery (#1859) #2454 queue/3069-1859-mcpx-faq @ 5956d05c
    • What landed: pkgs/mcpx/docs/faq.md (five verbatim question headings, explicit <a id> anchors for faq#do-you-like-mcp, #opencode-code-mode, #is-it-safe, #why, #examples, ≤120-word "we"-voice answers, one "more" link each, code-mode facts from the OPENCODE-V2.md correction block only); pkgs/mcpx/examples/ with four scripts + examples_test.go (fakemcp fixture, e2e daemon hygiene, stdout vs .expected.txt, so CI's go test ./... runs them) + docs/examples.md gallery.
    • Verified locally: go test ./examples/, go test ./internal/defaults/ (link test), gofmt — all clean. Full go test ./... left to CI.
    • Side fixes the new directory forced: link test now resolves a backticked path against the citing document too, and treats examples/servers/ as foreign (conformance clone); plugin/opencode/README.md names the browser skill example's real path.
    • State: parked 20 min for basic: test on PR docs(mcpx): the FAQ and a runnable examples gallery (#1859) #2454. On resume: read checks fresh, merge under the standing criteria, then remove work/*, queue/*, status/* labels.

  13. dezren39 commented on Oct 29, 2026

    @dezren39
    dezren39
    on Oct 29, 2026
    MemberAuthor

    🤖 Agent note · done (PR opened)

    • Agent: queue worker (repo-worker-code), OpenChamber scheduled lane
    • Session / ID: queue task 3069 (issue mcpx docs: the FAQ, in the notes' own voice #1859, follow-up of triage 2747)
    • Outcome: pr_opened — PR #2454 (queue/3069-1859-mcpx-faq, head 5956d05c), open, not draft, MERGEABLE, no unresolved review threads.
    • What landed: docs/faq.md (five verbatim question headings, fixed <a id> anchors, ~120-word answers, one "more" link each) plus a runnable examples gallery: examples/ (4 scripts + checked-in expected output), docs/examples.md, and examples/examples_test.go, which executes every script and diffs stdout so the gallery cannot rot.
    • Verified: go test ./examples/ pass; go test ./internal/defaults/ -run TestEveryDocumentationLinkResolves pass; gofmt clean. CI on the PR is in progress; merge is gated on the repo-wide merge-queue stall (ci: merge queue ejects every PR — no merge since #2233 (10:57Z), entries dropped 2-6 min into AWAITING_CHECKS #2403).
    • Queue: task 3069 completed pr_opened, ci: pending. Resume of the PR (checks → merge) is left to the standing PR shepherd path.
  14. dezren39
    added
    queue/queuedHas a queued task in the Supabase agent queue
    and removed
    queue/claimedQueue worker lifecycle state
    work/assignedQueue worker lifecycle state
    status/parkedDeliberately paused with a recorded resume condition
    queue/parkedQueue task is parked (waiting on CI, time, or an event)
    on Oct 29, 2026

  15. dezren39 commented on Oct 29, 2026

    @dezren39
    dezren39
    on Oct 29, 2026
    MemberAuthor

    🤖 Agent note · lease expired, requeued — work is done, only the closing verbs were missed

    • Agent: queue worker (repo-worker-code), OpenChamber scheduled lane
    • Session / ID: queue task 3069
    • What happened: the 45-minute lease on task 3069 expired between the PR opening and the park call (park_task: task 3069 is not claimed). No work was lost: branch queue/3069-1859-mcpx-faq @ 5956d05c is pushed and PR docs(mcpx): the FAQ and a runnable examples gallery (#1859) #2454 is open.
    • Resume brief: claim 3069 (or its successor packet), then just: read PR docs(mcpx): the FAQ and a runnable examples gallery (#1859) #2454's basic: test check, merge if green under the standing criteria (diff matches the issue: faq page + examples + gallery + the two link-test corrections), and clear work/*, queue/*, status/* labels. Nothing to implement.
    • Labels: reset to queue/queued to match the queue's own view after the expiry (the parked labels I set a minute earlier were reverted).

  16. dezren39 commented on Oct 29, 2026

    @dezren39
    dezren39
    on Oct 29, 2026
    MemberAuthor

    🤖 Agent note · green and enqueued in the merge queue

    • Agent: queue worker (repo-worker-code), OpenChamber scheduled lane
    • Session / ID: queue task 3069
    • PR: docs(mcpx): the FAQ and a runnable examples gallery (#1859) #2454 queue/3069-1859-mcpx-faq @ 5956d05c
    • Checks: basic: test pass (first run failed in internal/pool, which then failed to reproduce locally under go test ./internal/pool/ -count=1 — 19.0s, ok — and passed on rerun; flake, not this diff), basic: spec parity pass, basic: proxy port fallbacks pass, mcpx/examples ok in CI (3.98s), mergeStateStatus: CLEAN.
    • State: auto-merge enabled, entry in main's merge queue (AWAITING_CHECKS behind other PRs). No further implementation needed.
    • Remaining for whoever next holds a claim on this task: confirm the merge landed (merge_sha), then clear work/*, queue/*, status/* labels on mcpx docs: the FAQ, in the notes' own voice #1859. That is the only step left.

  17. dezren39 commented on Oct 29, 2026

    @dezren39
    dezren39
    on Oct 29, 2026
    MemberAuthor

    🤖 Agent note · green, waiting on the known merge-queue stall

  18. dezren39
    closed this as completedin #2454on Oct 30, 2026
  19. developing-today
    added
    status:done
    and removed
    status:in-review
    on Oct 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

queue/queuedHas a queued task in the Supabase agent queuestatus:done

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions