---
title: "Hand off tasks over MCP"
description: "Add cf-opencode mcp to Claude Code, OpenCode or another MCP client, so a local agent hands off tasks and reads the results as structured data."
---

> Documentation Index
> Fetch the complete documentation index at: https://cf-opencode.system3inference.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Hand off tasks over MCP

`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](https://cf-opencode.system3inference.dev/docs/guides/hand-off-a-task/) first.

## Before you start

1. Install cf-opencode on this machine: `cf-opencode init`.
2. Connect the checkout once: `cf-opencode connect`.
3. Set up GitHub, so the agent in the workspace can push. See [GitHub](https://cf-opencode.system3inference.dev/docs/guides/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

```sh
claude mcp add cf-opencode -- cf-opencode mcp
```

### OpenCode

Add a `servers` entry under `mcp` in `opencode.json`:

```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](https://cf-opencode.system3inference.dev/docs/guides/hand-off-a-task/#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](https://cf-opencode.system3inference.dev/docs/guides/hand-off-a-task/#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](https://cf-opencode.system3inference.dev/docs/guides/hand-off-a-task/#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.
- `directory` can name any git checkout on this machine. The CLI runs `git` there, and `git` reads that checkout's `.git/config`, which can run commands. The first task for a checkout also makes its workspace from the checkout's `origin` remote.

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_task` never sends local files.
- The tools cannot answer a waiting task. Answer it in OpenCode.

Source: https://cf-opencode.system3inference.dev/docs/guides/mcp/index.mdx
