OpenCode MCP server setup for a task backlog

Connect OpenCode to Autoplans, either through the opencode-autoplans plugin or as a remote MCP server in opencode.json.

The configuration

File: opencode.json in the project, or ~/.config/opencode/opencode.json · Transport: Streamable HTTP

{
  "mcp": {
    "autoplans": {
      "type": "remote",
      "url": "https://autoplans.dev/api/v1/mcp",
      "headers": { "Authorization": "Bearer apk_live_..." }
    }
  }
}

The endpoint is https://autoplans.dev/api/v1/mcp. Create the key in the dashboard under Settings → API keys; see Accounts and API keys.

Step by step

1
Create an API key in the dashboard under Settings → API keys.
2
Add the mcp block to opencode.json in the project root, or to ~/.config/opencode/opencode.json for every project.
3
Replace apk_live_... with the key, or write {env:AUTOPLANS_API_KEY} in its place and export the variable.
4
Run opencode mcp list and check that autoplans is connected.
5
Run opencode mcp debug autoplans if it is not, which tests the connection and reports what failed.
6
Ask the agent for your open tasks.

Specific to OpenCode

•The top-level key is mcp, not mcpServers, and each entry declares "type": "remote" or "type": "local". For a remote server, type and url are the only required fields; enabled, headers, oauth and timeout are optional.
•opencode.json substitutes {env:VAR} anywhere in the file, so a committed config can refer to the key without containing it. An unset variable is replaced with an empty string rather than being flagged, which sends "Bearer " and reads as a bad key.
•The opencode-autoplans plugin is the alternative: "plugin": ["opencode-autoplans"] in the same file loads thirteen task-shaped tools instead of the whole server. That is what keeps sessions working on models that reject a payload of around forty tool schemas. See /docs/opencode.
•The plugin is the same code the Autoplans desktop app and CLI bundle, and it surfaces your in-progress tasks when a session starts. Configuring the MCP server instead gives you every tool, including the telemetry ones the plugin leaves out.

What the agent can do once connected

Around forty tools: list and create projects, read the whole task graph in one list_tasks call, ask code_agent_get_task_with_dependencies whether a task is blocked, move it to in progress, comment on it, and mark it done. Every tool and its arguments is in the MCP tools reference; the server itself is described on the MCP server page.

curl -s https://autoplans.dev/api/v1/mcp \
  -H 'content-type: application/json' \
  -H "authorization: Bearer $AUTOPLANS_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Questions

How do I add the OpenCode MCP server for Autoplans?

Put the mcp block above in opencode.json, with your key in the Authorization header, then run opencode mcp list to confirm it connected. A "type": "remote" entry is one OpenCode connects to over the network, so nothing has to be installed locally. Project-level opencode.json applies to that folder; ~/.config/opencode/opencode.json applies everywhere, and the two are merged rather than one replacing the other.

Plugin or MCP server — which should I use with OpenCode?

The MCP server exposes everything, which is what you want when you are working across projects, editing branding or business plans, or reading telemetry. The plugin exposes a smaller, task-shaped set and shapes results for an agent rather than returning raw records, which matters on models and endpoints that refuse a large tool payload. Both read the same account, and you can start with one and switch.

Where does opencode.json go?

In the project root, next to the code, or at ~/.config/opencode/opencode.json for a setting you want everywhere. The project file is the better home for a backlog, since it travels with the repository — and if that repository also has .autoplans/project.json, tell the agent in AGENTS.md to read the projectId from it rather than listing every project to find the right one.

How do I check that OpenCode connected?

opencode mcp list shows every configured server and its authentication state, and opencode mcp debug autoplans tests one of them and prints what went wrong. Outside OpenCode, a tools/list request against the endpoint separates a bad key (401) from a free-plan account (403, because the hosted MCP server is a paid capability) from a working connection.

Checked against the OpenCode documentation on 2026-08-28.