Content
# OpenCode MCP Agent
[](https://github.com/arctan303/opencode-mcp-agent/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://www.npmjs.com/package/opencode-mcp-agent)
**English | [简体中文](README.md)**
Let your main AI Agent directly dispatch tasks to OpenCode - use the strongest model to make plans, and the most economical model to execute.
## Why do we need this tool?
In multi-agent workflows, you may encounter the following issues:
- 🧠 **Plan formulation** requires the strongest model (GPT-5.5, Claude Opus 4.6), but these models are expensive
- ⚡ **Code execution** consumes a large number of tokens (reading files, writing code, running tests), and using top models is wasteful
- 🔄 **Agent switching** requires manual copying of files, pasting context, and the process is fragmented
OpenCode MCP Agent solves these problems:
```text
Main Agent (GPT-5.5 / Opus 4.6)
→ Formulate plans, design architecture, and split tasks
→ Dispatch tasks directly to OpenCode via MCP
→ OpenCode uses economical models (DeepSeek / Mimo) for execution
→ Automatically returns results, status, and permission requests
```
**One-sentence summary**: Use the strongest brain for decision-making and the most economical hands for execution, with zero friction in between.
## Working Principle
```text
MCP Client (e.g., Codex, Claude Desktop)
→ OpenCode MCP Agent (MCP Server)
→ Managed OpenCode server (local runtime)
→ OpenCode agent, session, model, and tools
```
- Runtime binds to `127.0.0.1` with a random port, and credentials are stored only in process memory
- No need for OpenCode Desktop
- Supports any MCP client
## Verified Environments
| Component | Version |
|------|------|
| Operating System | Windows 11 25H2 |
| Node.js | v24.15.0 |
| Main Agent | Codex (GPT-5.5) |
| Execution Agent | OpenCode (DeepSeek v4 Pro) |
> This is the author's first MCP tool project. If you encounter issues in other environments, feel free to [submit an issue](https://github.com/arctan303/opencode-mcp-agent/issues) to report bugs or suggest improvements.
## Current Status
The core workflow has been completed and verified through automated testing and real runtime testing:
- Managed local OpenCode runtime
- Explicitly specified workspace and model
- Asynchronous tasks with persistent task records
- Session creation and reuse
- Progress, running tools, and blocking tool reporting
- OpenCode permission discovery and reply
- Quick two-stage cancellation
- Model and session discovery
The 1.0 version provides the first stable task-oriented MCP interface.
## Requirements
- Node.js 18 or later
- OpenCode CLI installed and configured
- MCP client supporting stdio server
Confirm OpenCode availability:
```bash
opencode --version
```
If OpenCode is not in the `PATH`, set `OPENCODE_BIN` to point to its executable file path.
## Quick Start
### Installation from npm
```bash
npm install -g opencode-mcp-agent
```
Then register in the MCP client:
```json
{
"mcpServers": {
"opencode-control": {
"command": "opencode-mcp-agent"
}
}
}
```
### Installation from Source
```bash
git clone https://github.com/arctan303/opencode-mcp-agent.git
cd opencode-mcp-agent
npm run check
```
Register in Codex:
```bash
codex mcp add opencode-control -- node /path/to/opencode-mcp-agent/server.mjs
```
General stdio MCP configuration:
```json
{
"mcpServers": {
"opencode-control": {
"command": "node",
"args": ["/absolute/path/to/opencode-mcp-agent/server.mjs"]
}
}
}
```
Restart the MCP client after changing the configuration.
## Typical Use Cases
### Scenario 1: Plan Formulation + Code Execution Separation
1. Use GPT-5.5 in Codex to formulate project plans and design documents
2. GPT-5.5 dispatches implementation tasks to OpenCode directly using `opencode_task_start`
3. OpenCode uses economical models (e.g., DeepSeek v4 Pro) for code execution
4. Main Agent tracks progress using `opencode_task_status`
5. Collect results using `opencode_task_result` after completion
### Scenario 2: Batch Task Parallelism
1. Main Agent splits large tasks into multiple sub-tasks
2. Dispatch sub-tasks sequentially using `opencode_task_start` (with `wait: false`)
3. Query task status and results in parallel
## Recommended Task Flow
1. Call `opencode_model_list` to view configured models.
2. Call `opencode_task_start`, explicitly specifying `workspace`, usually with `wait: false`.
3. Poll `opencode_task_status`.
4. If the task enters `waiting_permission` state, call `opencode_permission_list` to view requests, then call `opencode_permission_reply` to reply.
5. Use `opencode_task_result` to read the final result.
Task parameter example:
```json
{
"workspace": "C:\\projects\\example",
"model": "provider/model",
"prompt": "Analyze this project and report performance risks. Do not modify files.",
"wait": false,
"timeoutMs": 600000
}
```
`timeoutMs` is the maximum lifetime of OpenCode model and tool requests. It takes effect even if `wait` is `false` and is independent of MCP client timeout settings.
## MCP Tools
| Tool | Purpose |
|---|---|
| `opencode_task_start` | Create or continue OpenCode task |
| `opencode_task_list` | Find persisted bridge tasks |
| `opencode_task_status` | Refresh task, tool, session, and permission status |
| `opencode_task_result` | Read complete task result |
| `opencode_task_cancel` | Request cancellation, without blocking wait |
| `opencode_session_list` | List OpenCode sessions |
| `opencode_session_messages` | Read compact or raw session messages |
| `opencode_model_list` | List available OpenCode models |
| `opencode_permission_list` | List real pending permissions |
| `opencode_permission_reply` | Reply with `once`, `always`, or `reject` |
| `opencode_runtime_status` | Check managed runtime status |
| `opencode_runtime_start` | Start managed runtime |
| `opencode_runtime_stop` | Stop managed runtime |
Long-running calls should use `wait: false`. MCP requests are processed concurrently, so you can query status and reply to permissions while waiting for another request.
Cancellation is two-stage: `opencode_task_cancel` returns `cancelRequested: true` first; after OpenCode confirms session termination, the task becomes `cancelled`.
## Configuration
| Environment Variable | Purpose |
|---|---|
| `OPENCODE_BIN` | OpenCode executable file path |
| `OPENCODE_CONFIG` | OpenCode configuration file path |
| `OPENCODE_BRIDGE_STATE` | Task state JSON file path |
| `OPENCODE_BRIDGE_DEBUG_TOOLS=1` | Expose legacy/debug MCP tools |
By default, task state is stored in the user's local application state directory outside the repository.
## Security Model
- Managed server listens only on `127.0.0.1`.
- Random port and random Basic Authentication credentials are generated for each runtime startup.
- Runtime credentials exist only in the bridge process memory.
- The bridge does not store model supplier credentials.
- OpenCode permissions are forwarded, not bypassed.
- `always` authorization should be approved only after checking permission type and mode.
See [SECURITY.md](SECURITY.md) for security issue reporting.
## Development
```bash
npm run check
```
The `check` command runs syntax checks and Node.js test suites.
Build npm release artifacts:
```bash
npm run build
```
The build runs all checks and writes the tarball, `SHA256SUMS`, and `manifest.json` to `dist/`.
Project documentation:
- [Background / BACKGROUND.md](docs/BACKGROUND.md)
- [Architecture / ARCHITECTURE.md](docs/ARCHITECTURE.md)
- [Roadmap / ROADMAP.md](docs/ROADMAP.md)
- [Contributing / CONTRIBUTING.md](CONTRIBUTING.md)
- [Changelog / CHANGELOG.md](CHANGELOG.md)
## License
MIT
