mcpctl/docs/opencode-extension.md

mcpctl × opencode — native integration (TUI plugin)

Motivation

With Claude Code, mcpctl config claude --project X wires a project's MCP servers into the agent using .mcp.json, and with pi/prime-agent it ships a dedicated extension. This addon does the same for opencode:

1. a TUI plugin (open-mcpctl.tsx) that shows the active mcpctl project in opencode's bottom status row (the row that also carries the token counter / model / mode info) and lets you switch projects from inside the interface with a searchable picker, and
2. mcpctl config opencode which provisions it: writes the plugin into ~/.config/opencode/plugin/, registers it in opencode.json, provisions the plugin deps, and persists the active project.

Where pi had to reimplement an MCP client (pi has no MCP), opencode has first-class MCP support, so the plugin leans on opencode's own MCP machinery: switching a project re-points opencode's mcpctl MCP server at the new project's mcplocal endpoint ({mcplocalUrl}/projects/<project>/mcp) via the SDK client, and opencode enumerates those tools natively. No JSON-RPC code in the plugin.

How it works

The indicator (bottom status row)

The plugin registers a slot into api.slots.register({ slots: { app_bottom } }). app_bottom is the row opencode renders directly beneath the session footer statusline — i.e. beside the token counter / model / mode readout. It renders a compact mcpctl <project> segment in the theme's accent/text colours.

Switching projects

<leader>m (or the mcpctl.switch_project command in the command palette) opens a DialogSelect listing projects from mcpd with search-as-you-type filtering (active project first, then alphabetical). Picking one:

1. client.mcp.disconnect({ name: "mcpctl" }) — drop the previous project's tools,
2. client.mcp.add({ name: "mcpctl", config: { type: "remote", url, headers } })
   • client.mcp.connect(...) — point at the new project's mcplocal endpoint,
3. persists the choice to ~/.mcpctl/opencode-state.json,
4. updates the bottom-row indicator and fires a toast.

Because the tools travel over opencode's native MCP, they pick up begin_session gating exactly like any other mcpctl client. If a project is gated, opencode only exposes its begin_session tool until it is called.

State

The active project lives in ~/.mcpctl/opencode-state.json (immune to your shell's cwd) and is also inferred from a .mcpctl-project marker walk-up, mirroring the pi extension.

Deliverables

Artifact	Purpose
src/opencode-ext/open-mcpctl.tsx	Self-contained opencode TUI plugin (the addon)
mcpctl config opencode	CLI wiring: installs the plugin, registers it, provisions deps + skills
docs/opencode-extension.md	This document

Using it

mcpctl config opencode --project <name>

This:

1. writes ~/.config/opencode/plugin/open-mcpctl.tsx,
2. registers that .tsx in opencode.json under plugin (opencode's plugin auto-discovery only matches {ts,js}, so the explicit entry is required for a JSX plugin),
3. best-effort installs @opencode-ai/plugin + @opentui/* into the config dir's node_modules (opencode provisions the former but not the TUI peers a TUI plugin needs), and
4. syncs the project's skills into ~/.config/opencode/skill.

Restart opencode (or start a new session) — the active project and its MCP tools appear in the bottom status row. Switch with <leader>m.

Re-sync skills later:

mcpctl skills sync --agent opencode --project <name>

Layout

src/opencode-ext/
  open-mcpctl.tsx     # the plugin (JSX, self-contained)
  tsconfig.json       # typechecks against real @opencode-ai/plugin types

The plugin imports only opencode-bundled packages (@opencode-ai/plugin/tui, @opentui/solid, solid-js) and the node standard library — no @mcpctl/*, no ~/.claude.

Typechecking

The plugin ships as source: it is embedded into the CLI (src/cli/src/config/opencode-extension.ts, generated by scripts/generate-opencode-extension.ts) and written verbatim into ~/.config/opencode/plugin/. The CLI's own build never compiles it, so without a dedicated project nothing would check it against opencode's API — exactly how a slotted component with the wrong shape would ship.

src/opencode-ext/tsconfig.json closes that gap, checking against the real published @opencode-ai/plugin + @opentui/solid types (dev dependencies):

pnpm run typecheck        # includes typecheck:opencode-ext

After editing src/opencode-ext/*.tsx, regenerate the embedded copy or the CLI will keep installing the old sources:

npx tsx scripts/generate-opencode-extension.ts

A test (tests/config/opencode-extension-embed.test.ts) fails if you forget.

Authentication caveat

The plugin sends whatever bearer it finds in ~/.mcpctl/credentials. A locally running mcpctl-local daemon does not authenticate /projects/*, so this works — the header is simply ignored. mcplocal serve registers a token-auth preHandler that accepts only mcpctl_pat_ bearers (project mcptokens), so pointing it at an authenticated mcplocal serve needs a project mcptoken (mcpctl create mcptoken <name> --project <name>).