opencode · mcp setup

Connect ConvOps to OpenCode

Add a remote server named convops with the URL https://mcp.convops.app/ to opencode.json, then run opencode mcp auth convops. OpenCode gets ConvOps tools: tasks with workflows, steps one at a time, engine-checked gates and approvals, and a memory shared with every other client.

terminal · ~/platformadding

$

  • opening browser to sign in…
  • convops · authenticated
  • $ opencode mcp list → convops connected
tasksworkflowsgatesmemoryroutesschedules

example · the client's screens vary by version

server url
https://mcp.convops.app/
add it with
opencode.json entry
config lives in
opencode.json (project or global)
sign-in
opencode mcp auth
01what you get

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.

  1. Workflows OpenCode walks one step at a time, whichever model is configured.
  2. Gates evaluated by the engine, including approval gates that hold the step until an explicit approval is given.
  3. Memory and routes shared with teammates on Claude Code, Cursor or Codex.
  4. 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.

02what you need

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
OpenCodeA version with remote MCP servers and the opencode mcp commands.
A ConvOps accountThe Free plan works. Sign up at my.convops.app; a first sign-in without a workspace takes you to create one.
Server URLhttps://mcp.convops.app/
03setup steps

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. 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. 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. 3

    Check the status

    Lists every server and its auth status.

    terminal
    opencode mcp list
  4. 4

    Start a task

    Run opencode and 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.

opencode.json
"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.

04in use

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.

example · opencode · ~/platformmcp: convops

new session

Add a nullable region column to accounts.
tasks_create · Database migration attached · step 1 of 4
workflow_advance · write → dry run
Dry run on staging: 2.1M rows, no lock beyond 40 ms. Waiting to apply.
Off-peak is fine. Approved.
workflow_advance · approved · → apply
example · Database migrationrunning
  1. Write migrationnot handed over yet
  2. Dry runnot handed over yet
  3. Apply approvalapproval
  4. 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.

05OpenCode notes

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.

Where OpenCode reads its setup
FileScopeHolds
opencode.json (project root)This repositoryThe convops server entry, shared with the team
~/.config/opencode/opencode.jsonEvery projectYour personal server list
AGENTS.mdProject or globalCodebase conventions, not the process
06troubleshooting

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 unauthenticatedRun opencode mcp auth convops and finish the browser sign-in.
Sign-in loops or token errorsRun opencode mcp logout convops, then auth again.
Tools missing in one agentCheck the tools globs for that agent are not switching convops tools off.
CI has no browserUse "oauth": false with an Authorization header from an environment variable.
07questions

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.