cf-opencode mcp is an MCP server. It gives a local agent four tools to hand off a task and follow it. The agent gets the task record as structured data. It does not parse shell output.
The tools do what cf-opencode run and cf-opencode tasks do. Read Hand off a task first.
Before you start
- Install cf-opencode on this machine:
cf-opencode init. - Connect the checkout once:
cf-opencode connect. - Set up GitHub, so the agent in the workspace can push. See GitHub.
The server uses the install and the control token of this machine, in ~/.cf-opencode. It needs no other key.
Add the server
The server runs over stdio. The client starts it with the command cf-opencode mcp.
Claude Code
claude mcp add cf-opencode -- cf-opencode mcpOpenCode
Add a servers entry under mcp in opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"cf-opencode": {
"type": "local",
"command": ["cf-opencode", "mcp"]
}
}
}
}Other clients
Add a stdio server with the command cf-opencode mcp and no arguments.
If npm could not install the CLI globally, use npx cf-opencode mcp as the command.
The tools
| Tool | What it does |
|---|---|
handoff_task |
Starts a task in the workspace of a checkout, and returns at once. |
get_task |
Reads one task. Wakes nothing. |
wait_task |
Waits until the task is not running, for at most 280 seconds. |
list_tasks |
Lists the tasks of the workspaces of this machine, newest first. Wakes nothing. |
pull_task |
Fetches the branch of a task into the local checkout, as tasks <ses_…> --pull does. |
handoff_task
| Argument | Required | Meaning |
|---|---|---|
task |
Yes | The full task. The remote agent did not see your conversation. |
directory |
No | The git checkout. Default: the directory that the client started the server in. It must be that folder or a folder under it. Another path is refused. |
workspace |
No | The workspace ID. Default: the workspace of the checkout, as connect names it. |
title |
No | The session title. |
model |
No | provider/model. Default: the model of the workspace. |
allowDirty |
No | true starts the task when the checkout has changes that are not committed or pushed. |
branch |
No | Start from this branch as it is on origin, as run --branch does. The tool checks that origin has it. |
auto |
No | true: the remote agent runs with no permission prompts, as run --auto does. |
worktree |
No | true: start in a new git worktree in the workspace, as run --worktree does. |
newWorkspace |
No | true: start in a new workspace, as run --new does. Not with workspace or worktree. |
One task at a time uses the checkout of a workspace. When a task there is running or waiting, the tool fails with the fix set newWorkspace or worktree to true. See Run two tasks at once.
The tool runs the same preflight as run. The workspace clones from the Git remote. It does not see changes that are not committed or commits that are not pushed. The tool fails on these, unless allowDirty is true. See The preflight.
The tool adds the same closing instruction as run: commit, push the branch, open a pull request, and end with a Result: line.
The task text has at most 32000 characters.
If directory is outside the folder where the client started the server, the tool fails with Failed: <dir> is outside the folder this MCP server started in — fix: start the MCP server in that project, or leave directory out. A folder that is not a git checkout, with no workspace argument, fails with <dir> is not a git checkout.
The result has workspace, session and task. Give session to the other tools.
get_task and wait_task
| Argument | Required | Meaning |
|---|---|---|
session |
Yes | The ses_… ID that handoff_task returned. |
workspace |
No | The workspace. Default: the workspace of this machine that has the session. |
timeoutSeconds |
No, wait_task only |
1 to 280. Default 240. |
The result has workspace, result, task, live and at. result is the result record that cf-opencode tasks <ses_…> --json prints: the state, the summary, and the branch, commits, changed files and pull request that git read in the workspace. When an older Worker sends no result record, the server builds one from task. live is false when a paused workspace answered with its saved copy. wait_task also returns timedOut.
pull_task
| Argument | Required | Meaning |
|---|---|---|
session |
Yes | The ses_… ID of the task. |
workspace |
No | The workspace. Default: the workspace of this machine that has the session. |
directory |
No | The local git checkout. Default: the directory that the client started the server in. It must be that folder or a folder under it. |
The result has workspace, branch, commit, local (created, updated or current) and checkedOut. The tool changes no file and no checked-out branch, except a fast-forward of the checked-out branch when it has no changes. See Bring the branch to your checkout.
Most MCP clients stop a tool call after 5 minutes. For this reason, wait_task waits 280 seconds or less. When timedOut is true, the task still runs. Call wait_task again.
The task record
task is the record that cf-opencode tasks --json shows. It has id, title, state, started and, when known, updated, model, last and reason. A newer Worker adds fields, such as summary, error, branch, commits and pullRequest. The server passes every field on.
state is one of these:
| State | Meaning |
|---|---|
running |
The agent works. |
waiting |
The agent asks a question or a permission. Answer it with cf-opencode connect <workspace> --session <ses_…>. |
done |
The agent finished its turn. |
failed |
The turn stopped with an error, or did not start. |
stopped |
The session was stopped before it finished. A newer Worker reports it. |
Trust
The server acts with your control token for the agent that starts it. An agent that a web page or a repository prompt-injected can call the tools like you:
- It can start a task with any text in any workspace of this machine.
directorycan name any git checkout on this machine. The CLI runsgitthere, andgitreads that checkout’s.git/config, which can run commands. The first task for a checkout also makes its workspace from the checkout’soriginremote.
Add the server only to an agent that you would let run cf-opencode run. The tool results hold no token or password.
Errors
A tool that fails returns isError: true and one line: Failed: <cause> — fix: <action>. The agent can read the fix and try again.
Protocol
The server speaks MCP 2026-07-28, in which each request carries its protocol version. It also answers initialize for clients that use 2025-11-25 or 2025-06-18. Other versions get the error that the spec gives, with the list of supported versions.
The server writes only MCP messages to stdout. It writes logs to stderr.
Limits
- The server acts with the control token of this machine. A client that runs the server can start tasks in every workspace of the install.
handoff_tasknever sends local files.- The tools cannot answer a waiting task. Answer it in OpenCode.