⚙️ How It Works

mcp-opencode is a bridge between your AI assistant and opencode. It speaks MCP to your assistant on one side, and opencode's local HTTP API on the other.

🔄 The flow

1. On first use, query and list_models look up opencode's background service, the one server every TUI window shares, from the registration it keeps in opencode's state directory (address and password).
2. If it isn't running, they start it the way the TUI does (opencode serve --service) and wait for it to become ready. Set MCP_OPENCODE_URL (and MCP_OPENCODE_PASSWORD) to use a server of your own instead.
3. Each query call creates a temporary opencode session, sends the prompt, waits for the response, then deletes the session.
4. list_sessions, send and read work on sessions that already exist in your opencode windows. They find the background service the same way, plus the headless instances this MCP started. A window started with opencode --standalone runs a private server and can't be reached.
5. Authentication is handled entirely by opencode — configure your providers once in opencode and this MCP inherits them automatically.

🖥️ Why a local server

opencode already manages provider credentials, model registries, and sessions. Rather than re-implement any of that, mcp-opencode talks to opencode's own HTTP server and lets it do the heavy lifting. The model list you see is opencode's list; the auth is opencode's auth.

This is the heart of the zero-key delegation model — no credentials are stored in or pass through the MCP server.

♻️ Two kinds of session

query is ephemeral. Every query spins up a fresh opencode session and tears it down once the response is returned. There's no conversation state carried between calls — each prompt is self-contained. Pass everything the model needs in the prompt itself.

send is conversational. It talks to a session that already exists and never deletes it, so history carries over from message to message. Start opencode as usual and whatever your assistant sends shows up live in the window showing that session, where you can pick the conversation up yourself.