⚙️ 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, the server checks whether an opencode HTTP server is listening on the port of MCP_OPENCODE_URL (default 127.0.0.1:4096).
2. If it isn't, the server spawns opencode serve --port <port> in the background and waits for it to become ready.
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 discover the windows themselves: every opencode process listening on a local port (found with lsof, then probed) counts. A window started without --port opens no port and can't be seen.
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 with a port (opencode --port 4097) and whatever your assistant sends shows up live in that window, where you can pick the conversation up yourself. When the same project is open in two windows, send uses the lowest port and says so; only that window streams the exchange live.