This server lets you discover, monitor, and interact with multiple OpenCode AI coding instances running across different machines via SSH reverse tunnels.
Discover & refresh instances: List all connected OpenCode instances (list_instances) or force a re-scan with health checks (refresh_instances)
Manage sessions: List all sessions on a specific instance (list_sessions), retrieve session details and conversation history (get_session), or create new chat sessions (create_session)
Send messages: Send messages to a specific session (send_message), with an async option for long-running tasks to avoid timeouts
Monitor status: Check whether sessions are idle, busy, or retrying (get_status)
Control execution: Abort a running session (abort_session)
Fuzzy matching: All instance-targeting tools support substring matching (e.g. "laptop" matches "laptop-myproject"), and session IDs support prefix matching
Integration: Works with mcp-gateway Docker deployments and supports local testing without SSH tunnels
Supports Cloudflare Tunnels as a pluggable transport backend for connecting to OpenCode instances, providing an alternative to SSH reverse tunnels for secure discovery and transport.
Supports Tailscale as a pluggable transport backend to enable secure networking and connectivity between the MCP server and distributed OpenCode instances.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@opencode-mcp list all available opencode instances"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that discovers, monitors, and drives multiple OpenCode instances running across personal machines. Uses SSH reverse tunnels through a central relay for discovery and transport. Pluggable transport layer supports future backends (Tailscale, Cloudflare Tunnels, mDNS).
# 1. Install
npm install && npm run build
# 2. Start opencode with HTTP side-car (in a separate terminal)
# opencode-connected picks a random port and writes a registration file
ln -s ~/prg/opencode-mcp/scripts/opencode-connected ~/bin/opencode-connected
opencode-connected
# 3. Run with MCP inspector (in another terminal)
npx @modelcontextprotocol/inspector tsx src/index.ts
# Or run directly (stdio MCP server)
node dist/index.jsBoth opencode-connected and the MCP server default to /tmp/opencode-relay
for the registry directory — no configuration needed for local testing.
Related MCP server: agent-bus-mcp
┌──────────────────────────────────────────────┐
│ Relay machine (GCE / VPS / etc.) │
│ │
│ mcp-gateway ──── opencode-mcp (stdio) │
│ │ │ │
│ │ reads /tmp/opencode-relay/ │
│ │ or RELAY_REGISTRY_DIR │
│ │ │ │
│ OAuth localhost:10001 ──┐ │
│ front localhost:10002 ──┤ opencode│
│ localhost:10003 ──┘ APIs │
│ │
│ sshd: accepts reverse tunnels │
└──────▲──────────▲───────────▲────────────────┘
│ │ │
ssh -R ssh -R ssh -R
│ │ │
laptop desktop laptop
(oc:4823) (oc:4567) (oc:4901)The MCP server runs on the same machine that accepts SSH reverse tunnels.
It reads registration JSON files from a directory, health-checks each
registered port on localhost, and creates OpenCode SDK clients for healthy
instances. All OpenCode API calls go through localhost:{tunnel_port}.
OpenCode binds to 127.0.0.1 (default) — the SSH tunnel is the auth
boundary. No passwords needed.
Tool | Input | Description |
| — | List all discovered instances with status (idle/busy) and recent session |
|
| Send a message to the most recent session; set |
|
| Read the last N messages from the most recent session |
Instance names support fuzzy substring matching (e.g. "laptop" matches
"laptop-myproject").
Variable | Default | Description |
|
| Directory containing registration JSON files |
|
| How often to refresh instance list (ms) |
|
| Timeout for health-checking each instance (ms) |
|
| Transport backend ( |
|
| Timeout for streaming send responses (ms) |
opencode-connected scriptVariable | Default | Description |
| — | SSH command to reach relay. If unset, local only. |
|
| Registry directory (local or on relay) |
|
| Instance name for registration |
Each file in RELAY_REGISTRY_DIR is a JSON file named {instance-name}.json:
{
"name": "laptop-myproject",
"hostname": "laptop",
"port": 10042,
"localPort": 4823,
"cwd": "/home/user/projects/myproject",
"connectedAt": "2026-03-14T10:30:00Z"
}Files are written by opencode-connected (locally or on the relay via SSH).
The MCP server prunes files whose ports fail health checks.
Use opencode-connected instead of bare opencode to start the TUI with
an HTTP side-car:
# Install (symlink)
ln -s ~/prg/opencode-mcp/scripts/opencode-connected ~/bin/opencode-connected
# Local only (no tunnel, writes registration to /tmp/opencode-relay/)
opencode-connected
# With relay (set RELAY_SSH_CMD in your shell profile)
export RELAY_SSH_CMD="gcloud compute ssh mcp-gateway --zone=us-central1-a --project=my-project --"
opencode-connected
# Or with direct SSH
export RELAY_SSH_CMD="ssh user@relay.example.com"
opencode-connected
# Pass extra args to opencode (after --)
opencode-connected -- -dThe script:
Picks a random available local port (4096-5095)
Starts opencode TUI with --port (enables HTTP side-car on 127.0.0.1)
If RELAY_SSH_CMD is set: establishes SSH reverse tunnel with auto-retry
Registers the instance (lazily creates the registry directory)
Cleans up the registration file on exit
Note: opencode without --port does not start an HTTP server.
The --port flag is what enables the HTTP side-car alongside the TUI.
Multiple instances in the same directory: The instance name defaults to
$(hostname)-$(basename $PWD). If you run multiple opencode instances in
the same directory, they'll compete for the same registration file — the
last one wins and the others become invisible to the MCP server. To avoid
this, set INSTANCE_NAME explicitly:
INSTANCE_NAME=my-tests opencode-connected
INSTANCE_NAME=my-refactor opencode-connectedFor work machines with different MCP configs, set OPENCODE_CONFIG in your
shell profile — the script does not handle config selection.
To add opencode-mcp to an existing mcp-gateway Docker deployment:
npx -y opencode-mcp # or add to gateway's SERVERS dict# docker run additions:
--network=host # reach SSH tunnel ports on host's localhost
-v /tmp/opencode-relay:/tmp/opencode-relay:ro # read registration files
-e RELAY_REGISTRY_DIR=/tmp/opencode-relay--network=host is required because SSH reverse tunnels bind on the
host's localhost. The container needs to reach those ports directly.
Add to the gateway's server configuration:
{
"mcpServers": {
"opencode": {
"command": "npx",
"args": ["-y", "opencode-mcp"],
"transport": "stdio",
"env": {
"RELAY_REGISTRY_DIR": "/tmp/opencode-relay"
}
}
}
}# On a client machine:
export RELAY_SSH_CMD="gcloud compute ssh mcp-gateway --zone=us-central1-a --project=my-project --"
opencode-connected
# From the chat interface, the LLM can now call:
# instances → sees the connected instance
# send → interacts with it
# read → sees what's been happeningopencode-mcp/
├── src/
│ ├── index.ts # MCP server entry + transport factory
│ ├── types.ts # RegistrationFile, OpenCodeInstance
│ ├── registry.ts # Instance cache + OpenCode SDK client mgmt
│ ├── transport/
│ │ ├── interface.ts # Abstract Transport interface
│ │ └── local-relay.ts # File-based registry + localhost health checks
│ └── tools/
│ └── simplified.ts # instances, send, read
├── scripts/
│ └── opencode-connected # Client: random port + tunnel + exec opencode TUI
├── plans/
│ └── architecture.md # Design doc + future work
├── package.json
├── tsconfig.json
└── .env.examplenpm install
npm run dev # run with tsx (no build step)
npm run build # compile TypeScript
npm start # run compiled outputSSH tunnels: the auth boundary — standard SSH key or gcloud auth
Tunnel ports: bound to host's localhost only, not externally accessible
OpenCode binding: 127.0.0.1 by default — not network-accessible
MCP transport: stdio (no network exposure); OAuth via mcp-gateway
Registration files: contain only name, hostname, port, cwd — no credentials
List all connected opencode instances with their current status (busy/idle). Call this to see what machines are available.
Inputs: no named parameters.
Read the last few messages from the most recent opencode session on an instance. Use this to see what has been happening without sending a new message.
Inputs: instance (required), message_limit.
Send a message to the most recent opencode session on an instance. Streams the response back in real-time. Set abort=true to stop a running task instead of sending a message.
Inputs: instance (required), message, abort.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 3 tools
Each tool has a clearly distinct purpose: listing instances, reading session history, and sending messages. No overlap or ambiguity.
All tool names are lowercase and concise, but 'instances' is a noun while 'read' and 'send' are verbs, creating a slight pattern inconsistency.
Three tools cover the essential operations for interacting with opencode instances (list, read, send) without unnecessary bloat.
Core workflows are covered, but there is no tool to select a specific instance or start a new session, which are minor gaps.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
A MCP server built for developers enabling Git based project management with project and personal…
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
