What do you get in OpenCode once ConvOps is connected?
OpenCode runs with the model you choose. ConvOps keeps the process the same whichever model does the work, and it is the same process when OpenCode runs unattended.
- Workflows OpenCode walks one step at a time, whichever model is configured.
- Gates evaluated by the engine, including approval gates that hold the step until an explicit approval is given.
- Memory and routes shared with teammates on Claude Code, Cursor or Codex.
- The same workflow attended in your terminal or unattended on an executor.
ConvOps is the operations layer for AI agents. It holds your team's process as workflows with gates, a shared memory, scheduled and unattended runs, programs, a plan board, metrics and a full audit trail. It does not sell or host models. OpenCode does the work. The steps, gates and decisions come from the ConvOps workflow engine, and the approvals and audit trail from governance.
What do you need to connect OpenCode to ConvOps?
A OpenCode setup that supports remote MCP servers, a ConvOps account, and the server URL. Plans start free; see pricing for limits.
| You need | Detail |
|---|---|
| OpenCode | A version with remote MCP servers and the opencode mcp commands. |
| A ConvOps account | The Free plan works. Sign up at my.convops.app; a first sign-in without a workspace takes you to create one. |
| Server URL | https://mcp.convops.app/ |
How do I add the ConvOps MCP server to OpenCode?
OpenCode reads opencode.json in the project root and ~/.config/opencode/opencode.json globally, and merges them.
- 1
Add the remote server
Put this in the project file to share it with the repository, or in the global file for every project.
opencode.json { "$schema": "https://opencode.ai/config.json", "mcp": { "convops": { "type": "remote", "url": "https://mcp.convops.app/", "enabled": true } } } - 2
Sign in
OpenCode starts OAuth when the server answers 401, or you can start it yourself. Your browser opens the ConvOps sign-in.
terminal opencode mcp auth convops - 3
Check the status
Lists every server and its auth status.
terminal opencode mcp list - 4
Start a task
Run
opencodeand ask: "Use ConvOps to start a migration task and follow its workflow."
Prefer an API key?
For CI or a shared runner, turn OAuth off and send an API key from the ConvOps app (Settings, API Keys). OpenCode reads it from the environment.
"convops": {
"type": "remote",
"url": "https://mcp.convops.app/",
"oauth": false,
"headers": { "Authorization": "Bearer {env:CONVOPS_API_KEY}" }
}Official reference: OpenCode: MCP servers, OpenCode: rules and AGENTS.md. We checked these steps against those docs on . OpenCode updates its interface often; when a menu name differs, the vendor docs are current.
What does a governed task look like in OpenCode?
A database migration. The dry run is a step like any other; applying to production waits for a person, whichever model OpenCode is running.
new session
- Write migrationnot handed over yet
- Dry runnot handed over yet
- Apply approvalapproval
- Applynot handed over yet
example
Each tool row is OpenCode calling ConvOps. The engine hands over one step, checks the gate when the agent asks to advance, and holds the run at an approval gate until an explicit approval is given, recorded with the account that gave it. The same task can be picked up later, by you or by a teammate in another client, at the step where it stopped.
What should OpenCode users know about AGENTS.md, context and unattended runs?
AGENTS.md first. OpenCode reads AGENTS.md from the project and ~/.config/opencode/AGENTS.md, and falls back to CLAUDE.md when there is no AGENTS.md. Keep it about the codebase; put ordered process in ConvOps workflows, where each step brings its own instructions (why long instruction files fail).
Watch the context. OpenCode warns that MCP servers add to your context. You can switch ConvOps tools off for agents that do not need them with a glob in the tools key, for example "convops*": false, and on again per agent.
Attended and unattended. In your terminal, OpenCode is the attended client. ConvOps executors can also dispatch unattended runs to OpenCode: on your own OpenCode server, or one pod per run on your own Kubernetes. The approval gates still stop the run. The unattended runs on Kubernetes guide walks through the setup.
| File | Scope | Holds |
|---|---|---|
| opencode.json (project root) | This repository | The convops server entry, shared with the team |
| ~/.config/opencode/opencode.json | Every project | Your personal server list |
| AGENTS.md | Project or global | Codebase conventions, not the process |
Why is ConvOps not showing up in OpenCode?
Almost always one of two things: the sign-in has not finished, or the server is off for this session. Start with the first row.
| Symptom | Fix |
|---|---|
| opencode mcp list shows it unauthenticated | Run opencode mcp auth convops and finish the browser sign-in. |
| Sign-in loops or token errors | Run opencode mcp logout convops, then auth again. |
| Tools missing in one agent | Check the tools globs for that agent are not switching convops tools off. |
| CI has no browser | Use "oauth": false with an Authorization header from an environment variable. |
What else do people ask about ConvOps in OpenCode?
Short answers, checked against the OpenCode documentation linked above.
Does ConvOps work with any model in OpenCode?
Yes. ConvOps does not pick or sell the model. It serves workflows over MCP, and OpenCode uses the model you set, attended or in an isolated run. Isolated runs use the providers connected to your workspace, and your own OpenCode server can use your own models, so model choice stays with you, per run.
Can ConvOps run OpenCode unattended?
Yes. ConvOps executors can dispatch a task to your own OpenCode server or to one pod per run on your own Kubernetes. A schedule can create and dispatch the task at a time and in the time zone you set. The workflow and its gates are the same as in an attended session.
Project or global opencode.json?
Project opencode.json to share the ConvOps server with everyone on the repository, global for yourself. OpenCode merges both, so a project entry sits on top of your personal setup. Each person still signs in with their own ConvOps account, so the audit trail shows who did each step.
Where does OpenCode store the ConvOps token?
Per OpenCode's docs, MCP OAuth tokens are stored in ~/.local/share/opencode/mcp-auth.json. That file holds your ConvOps sign-in, so keep it out of anything you share. To sign out, run opencode mcp logout convops, then opencode mcp auth convops to sign in again.
Can I connect OpenCode to ConvOps in CI without a browser?
Yes. Set "oauth": false on the ConvOps server in opencode.json and send an Authorization header with an API key from the ConvOps app (Settings, API Keys), read from an environment variable. Keep the key out of version control. People at a desk keep the browser sign-in, so each acts under their own account.
Can OpenCode and Claude Code work the same ConvOps task?
Yes. The task, its workflow and its current step live in ConvOps, not in the client. One person can start a task in OpenCode with the model of their choice and another can finish it in Claude Code, reading the same step instructions and notes. The audit trail keeps the agent's label apart from the verified person on each step.