⚙️ 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 the opencode HTTP server is running on 127.0.0.1:4096.
2. If it isn't, the server spawns opencode serve 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. 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.

♻️ Sessions are 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.