mcpx docs: plugin pages -- plugins, compatibility, interface and config, opencode v1 and v2, vibeMcp #1855

Relocated from dezren39/darwin-nix#148 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

This issue covers the level-2 plugin pages: plugins, plugin compatibility, plugin interface & config, the opencode v1 plugin, the opencode v2 plugin, and vibeMcp. Anchors are under plugins#… in #146's page map. The pages may split into a plugins index plus an opencode page, with the same anchors either way.

"Plugin" means two different things in this project, and the pages must say which one each section means:

Nearly everything in the notes' plugin lines is about the first meaning. "vibeMcp" appears nowhere in the repo, and its meaning is the first open question.

Original notes

Source-notes lines 1, 2, 7, 49-52 (parents) and 72-77 (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
          • plugins
          • plugin compatibility
          • plugin interface & config
          • opencode v1 plugin
          • opencode v2 plugin
          • vibeMcp

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

Paths are relative to pkgs/mcpx/ on main (d0b7e01); re-checked at 05c78b2 in the 2026-09-30 issues pass, after #171 changed the plugin settings.

• What ships:

  • plugin/opencode/mcpx-session.ts, the opencode adapter: hooks, tools, toasts, session id.
  • plugin/opencode/mcpx/daemon.ts, the portable core: DaemonClient, the discovery ladder, the remembered-choice file. It imports nothing from opencode.
  • mcpx-tui.tsx, an optional TUI picker.
  • Four skills: mcpx-basics, mcpx-observability, mcpx-browser, mcpx-daemon.

  Source: plugin/opencode/README.md "The files".

• How it is installed: by hand with cp -R into ~/.config/opencode/plugin/, and mcpx/ must stay a subdirectory (README "Install"). Nothing in ~/.config/nix outside pkgs/mcpx references it (git grep mcpx-session origin/main finds nothing), so the Nix config does not install it.

• Versions: opencode v1 is 1.18.31; the v2 CLI opencode2 is 2.0.3 (docs/opencode-plugin.md §1). v1 plugins do not load in v2 (build(deps): bump actions/checkout from 3 to 4 #47). v1.18.31 runs both plugin systems, so a v2 plugin file dropped into v1 is loaded by the v2 host and rejected, harmlessly, by the v1 loader (§1).

• No binary needed: the plugin needs no mcpx on PATH (Bump rustls-webpki from 0.100.1 to 0.100.2 in /sources/pavex/examples/realworld #44, closed, fixed in chore(deps): bump build/buck/preludes/buck2-prelude from d956689 to 880be56 #53). It reaches the daemon over the unix socket. It spawns mcpx --json status only at rung 4 of discovery, the last fallback, used when a binary exists and the daemons are too old to answer GET /v1/resolve (plugin/opencode/README.md:99-112, plugin/opencode/mcpx/daemon.ts). backend: v1 never spawns, and bin: "" forbids spawning (README:83-85). The pages say "never needs the binary", not "never runs it".

• Two sources for plugin configuration (as written at d0b7e01, struck where Phase 2: delegated Manage cannot add members #171 changed it):

  • The registry has 9 plugin.* settings: backend, bin, binArgs, discoveryRetry, env, instructions, skills, toolTiming, tools (docs/configuration.md "plugin"). At 05c78b2 the registry has 10: those minus skills (deleted, since nothing registers skills), plus remember and annotate (added) (internal/settings/plugin.go; docs/configuration.md:346-355).
  • The README's options table has 13 (plugin/opencode/README.md:79-93). Six of them are not plugin.* settings: endpoint and socket (mapped to MCPX_DAEMON_ENDPOINT/MCPX_ENDPOINT and MCPX_SOCKET), remember, daemonTools, annotate, headless. Four of them are not plugin.* settings: endpoint and socket (mapped to MCPX_DAEMON_ENDPOINT/MCPX_ENDPOINT and MCPX_SOCKET), daemonTools and headless. Phase 2: delegated Manage cannot add members #171 allowlisted all four with a reason each (pluginEnvAllowed, internal/settings/consumed_test.go:188-200). headless and daemonTools have defaults computed at boot, so a declared default would be wrong in one realm.
  • discoveryRetry is in the registry, and since Phase 2: delegated Manage cannot add members #171 actually read (mcpx-session.ts:196), but is still missing from the README table. skills is gone.
  • docs/configuration.md:85-86 says "The plugin reads process.env directly, so the variable names are the contract between the two and a test pins them". The test pins only the registry's names. Since Phase 2: delegated Manage cannot add members #171 this holds in both directions. TestEverySettingIsReadSomewhere requires every plugin.* variable to appear in the plugin's sources, and TestThePluginReadsNoUndeclaredSetting (consumed_test.go:209) fails on any variable the plugin reads that is neither a setting nor allowlisted. What no test pins is the README table itself.

• Stale variable name: docs/opencode-plugin.md:406 (§6) says the plugin sets "MCPX_SESSION, MCPX_CALL and friends". The code sets MCPX_SESSION_ID (mcpx-session.ts:670), MCPX_CALL_ID (:677) and MCPX_PARENT_SESSION_ID (:713), which are the names session and parent-session scopes read (story.md "Sharing and scope"). The pages use the code's names. This is a doc fix only. MCPX_SESSION is a different, live variable: mcpx sets it for each script and the generated client reads it (internal/codegen/emit.go:253). It must not be renamed. MCPX_CALL exists nowhere (Root flake check fails on nixosConfigurations due to missing clan-core.clanModules #159 item 13, struck and corrected).

• Other harnesses: codex, claude code, pi and manus have no plugin. Update Rust crate anyhow to 1.0.75 #48 designs a harness-free core plus adapters. docs/opencode-plugin.md §5 lists what an adapter must provide. Only (1) a directory and (2) a session identifier are required; everything else degrades.

• Commands referenced below that are dispatched but missing from Commands(): mcpx api and mcpx adapter (see ⚡ Bolt: Optimize hash calculation for cursor colors #147 Finding 1). All others are in Commands().

Content per item

plugins#plugins

Approaches: naming the two meanings.

• A (least recommended): use "plugin" for both and rely on prose to tell them apart. A reader who arrives from a search engine at "plugin config" has no way to know whether it is about opencode or about extending mcpx. The confusion then spreads into issues, and into the agent twin (Update module github.com/jackc/pgx/v5 to v5.9.2 [SECURITY] #120), where an agent will happily mix them up.
• B (middle): rename one of them everywhere, for example harness plugins become "integrations", including plugin/ in the repo. This is clear, but it fights every harness's own vocabulary (opencode calls them plugins, and so will its users). It also needs a code-and-path rename that belongs to Update Rust crate anyhow to 1.0.75 #48, not to docs.
• C (recommended): keep the word and qualify it every time. The page is titled "Plugins" and has two top-level sections: "Harness plugins: mcpx inside your agent" and "mcpx plugins: extending mcpx". The second is a short status stub ("not built; designed in chore(deps): bump build/buck/preludes/buck2-prelude from d956689 to 2901d28 #80") until chore(deps): bump build/buck/preludes/buck2-prelude from d956689 to 2901d28 #80 lands. A glossary entry and a one-line callout at the top of every plugin page say which meaning the page uses. This matches the words users will search for, needs no rename, and scales when chore(deps): bump build/buck/preludes/buck2-prelude from d956689 to 2901d28 #80 ships.

Content for the harness-plugin section:

• What a harness plugin adds, and that it is optional. Any harness with a shell can use mcpx through AGENTS.md alone. The plugin adds:
  • the session id, so session-scoped servers persist across commands (README "Why");
  • the socket fast path (0.17 ms versus a 23 ms spawn);
  • optional tools, a system-prompt line, timing records and the daemon picker.
• Hosts that only speak MCP need no plugin: mcpx serve --transport stdio or /mcp, linking modes#server-modes (🎨 Palette: Add aria-labels to search and goto-line inputs #146).

plugins#plugin-compatibility

A matrix. Every cell cites a source or says "unknown", with nothing guessed:

Also one runtime note from the README: the core dials the socket with Bun's fetch(url, {unix}). A Node-based harness has to use MCPX_DAEMON_ENDPOINT and the TCP listener instead.

plugins#plugin-interface-and-config

Two interfaces and one configuration surface:

1. Plugin to harness. The four opencode hooks mcpx uses (docs/opencode-plugin.md §2.2), and what each one degrades to without it (§6).

2. Plugin to daemon. DaemonClient / connect(), and the discovery ladder (plugin/opencode/README.md:104-112): 0 a named endpoint or socket; 1 the choice remembered for this directory; 2 the daemon-*.json info files (the usual case, no binary); 3 GET /v1/resolve; 4 spawn mcpx --json status, the only rung that runs the binary, used as a last fallback and never under backend: v1 or bin: ""; 5 ask the user; 6 the best candidate, with a warning (docs/plugin-discovery.md §2-§5).

3. For authors of plugins for other harnesses: the adapter contract (§5's six items, two of them required). This is what Update Rust crate anyhow to 1.0.75 #48 builds on.

4. Configuration:

   • precedence is plugin option > environment variable > default;
   • options reach the plugin only when it is named in opencode config as a two-element array (README "Passing options");
   • the options table must be generated from one list.

   Approaches for that one list (revised 2026-09-30: Phase 2: delegated Manage cannot add members #171 settled part of this. It registered remember and annotate, deleted skills, and allowlisted the other four with reasons. The original C, "declare every plugin option in the registry", is kept below as B because Phase 2: delegated Manage cannot add members #171 rejected it for two of the four):

   • A (least): the README table stays the source. It already disagrees with the registry: it omits discoveryRetry.
   • B (middle): register the remaining four too (the original recommendation): endpoint and socket as aliases of daemon.endpoint and a socket setting, and headless and daemonTools as settings. The existing plugin-variable test then pins all of them, and 🎨 Palette: Improve accessibility of editor search panel #144 generates the table. The cost is the one Phase 2: delegated Manage cannot add members #171 recorded: headless and daemonTools default to something computed at boot, so any declared default is wrong in one of the two realms the plugin runs in. MCPX_SOCKET is also read before any settings exist.
   • C (recommended): generate the table from the registry's plugin.* settings plus a declared list of the non-setting options. Move pluginEnvAllowed out of the test into a non-test declaration that gives each entry its option name, variable, default description and effect. The test and the generator both read it. That declaration is the plugin slice of Phase 2: membership, delegation, groups, and server config #172's table of non-setting variables, so use Phase 2: membership, delegation, groups, and server config #172's shape rather than inventing one. This keeps Phase 2: delegated Manage cannot add members #171's reasoning, needs no behaviour change, and makes the README and docs table impossible to leave incomplete, which is exactly how discoveryRetry went missing.

plugins#opencode-v1-plugin

What ships today:

• the files, the install commands and why mcpx/ must stay a subdirectory;
• skills installation;
• options via config;
• what gets injected (README "What gets injected"; minimal/standard/full via plugin.env);
• the tools: mcpx_discover, mcpx_exec and mcpx_observe, off by default because each adds a tool to every request; plus the daemon tools;
• instructions, toolTiming, trace ids, the TUI picker.

One paragraph on interplay with opencode's own code mode (OPENCODE_EXPERIMENTAL_CODE_MODE, #149 faq#opencode-code-mode): the two do not conflict, and the plugin needs nothing in opencode's mcp config.

Install friction is real: cp -R by hand, and the Nix config does not install it. Open question 4 asks whether the page should promise a packaged install.

plugins#opencode-v2-plugin

Approaches: documenting something not yet built.

• A (least recommended): leave it out until build(deps): bump actions/checkout from 3 to 4 #47 ships. The notes list it, and a v2 user who lands on the plugin pages would find nothing about their version, not even that nothing exists.

• B (middle): document the planned design (the §4 lists: unnecessary / possible / breaks / same). This is accurate as a design, but it reads as a feature, and a reader will try it.

• C (recommended): a short status section. It says: "Not built; tracked in build(deps): bump actions/checkout from 3 to 4 #47. On opencode v2 today:"

  1. shell + AGENTS.md works, with no session id, so session-scoped servers are isolated per call;
  2. alternatively add mcpx serve --transport stdio to v2's mcp config.

  It also states what the rewrite will change, in four bullets taken from §4, and links the compendium (docs(id): design plan, research, and n0 relay default #152) for the full design.

  One caveat for option 2: v2 defaults MCP servers to code mode, so mcpx's own tools end up wrapped inside v2's code mode. OPENCODE-V2.md records that v2 ships mcp-codemode-defaults.ts to turn that off for servers that are themselves code mode. Whether it recognises mcpx is unknown (open question 3).

  This is honest, useful today, and cannot be mistaken for a shipped feature.

plugins#vibemcp

The term does not appear in the repo, in ~/git, or in the other notes (rg -il 'vibe.?mcp' finds only the notes files). A web search on 2026-09-30 found four unrelated projects with the name:

Candidate readings, for the user to choose from (open question 1):

1. "Vibe-coding an MCP server": getting tools without writing a server. mcpx already does three versions of this:

   • a command-line program becomes tools through paths.adapters (mcpx adapter);
   • an OpenAPI document becomes tools through mcpx api --spec or paths.apis;
   • a saved script or recipe runs by name (mcpx recipes, mcpx run).

   Caveat: adapter and OpenAPI tools are MCP tools, not script namespaces, so they are absent from tools.<ns> (Bump build/buck/preludes/buck2-prelude from d956689 to f12c8d1 #102). chore(deps): bump build/buck/preludes/buck2-prelude from d956689 to 36464cf #83 plans to make them first-class. If this is the reading, the page probably moves out of the plugin block, to configuration#server-config or an "extending mcpx" page.

2. A named external project, most plausibly the multi-agent browser (VibeTechnologies). It would appear as a comparison, or as a server known to work behind mcpx.

3. Vibe-coding with mcpx: the user describes a task and gets a script back (mcpx prompt, recipes, POST /v1/intent; docs/consumer.md).

4. A planned name for an mcpx mode or product not yet written down anywhere.

Until this is answered, the page map keeps the item verbatim at plugins#vibemcp, and the page holds a one-line placeholder rather than a guess.

Open questions

1. What does "vibeMcp" mean? One of the four readings above, or something else? This decides whether the page stays under plugins.
2. Plugin config source (Approach C in interface & config): register the six extra plugin options in the registry? Phase 2: delegated Manage cannot add members #171 registered two and allowlisted four with reasons. Is that split final? And should the README table be generated from the registry plus Phase 2: membership, delegation, groups, and server config #172's declared list, as C proposes?
3. opencode v2 as an MCP host of mcpx: does v2's code-mode default wrap mcpx's mcpx_exec, and should mcpx declare itself so mcp-codemode-defaults.ts turns code mode off for it?
4. Packaging: should the v1 plugin be installable from the Nix config or a release artifact before the page describes installing it? Or does the page document the cp -R flow as-is (amd host fails at evaluation: no outputHashes for p2panda-core-0.7.1 #158)?
5. The compatibility matrix: who fills in the "unknown" cells for codex, claude code, pi and manus? Update Rust crate anyhow to 1.0.75 #48 is where the work lives. The docs should not claim support before an adapter exists.

Docs checks run in CI; see the testing trackers under #91 (CI pipeline #95, integration/environments #97).

Ease · Impact · Related

Ease S-M (mostly assembly from plugin/opencode/README.md and docs/opencode-plugin.md; the config table waits on the registry decision; vibeMcp waits on the user) · Impact med: it matters to every opencode user and to anyone porting to another harness · Depends on / related: #94, #44 (closed, fixed in #53), #47, #48, #80, #82, #83, #102, #88, #146, #147, #149, #144, #158, #152, #153, #159 (item 9: the plugin option sources; item 13: the MCPX_SESSION doc line), #172 (the declared list of non-setting variables that Approach C builds on)

Security/auth deferred; see tracker.