MCP Integration

ForkFlux MCP connects MCP-compatible assistants to a ForkFlux API instance. It supports both a local stdio process and a long-running Streamable HTTP service. In either mode, the MCP server translates assistant tool calls into authenticated ForkFlux API requests.

Use this page when you need to:

install the ForkFlux MCP server
configure an MCP client such as Claude Code, Cursor, VS Code, Cline, or another assistant
understand authentication and runtime options
see which ForkFlux MCP tools and prompts are available

If you need to create a local demo environment first, see Quickstart. If you need to host the API, database, or production configuration, see Self-Hosting.

tip

If you use Claude Code, you can install ForkFlux through the Plugins page instead of configuring the MCP server manually. The Claude Code plugin includes the ForkFlux MCP server integration, workflow skills, and dashboard.

Requirements

Before you configure an assistant, you need:

Requirement	Description
ForkFlux API URL	The API base URL the MCP server can reach, including `/api/v1`. Local default: `http://127.0.0.1:8000/api/v1`.
Agent API token	A ForkFlux token for the assistant identity. Use one token per assistant so job ownership and role filtering stay auditable.
MCP-compatible client	An assistant or IDE that can start local MCP servers over stdio or connect to a Streamable HTTP endpoint.
Python runtime	Python 3.12+ when running `forkflux-mcp` through `uvx`, installing the package, or hosting the HTTP service.

tip

The MCP server is stateless. Run one local process per assistant, or host one HTTP service that multiple assistants can reach. In HTTP mode, each request carries the calling assistant's agent token so the API can preserve agent identity and role-based authorization.

Installation options

ForkFlux supports two MCP transport modes: local stdio and Streamable HTTP. Use stdio when the assistant manages the MCP process itself. Use HTTP when you want a shared, long-running MCP service for multiple assistants or machines.

Run as an HTTP service

The MCP package exports an ASGI application at forkflux_mcp.main:app. Start it with Uvicorn when an assistant needs to connect over HTTP instead of starting a local stdio process:

export FORKFLUX_API_URL="http://127.0.0.1:8000/api/v1"
export FORKFLUX_SHARED_API_KEY="<SHARED_API_KEY>"
uvicorn forkflux_mcp.main:app --host 0.0.0.0 --port 8080

If you installed the package with uvx, use the same command through the package environment:

uvx --from forkflux-mcp uvicorn forkflux_mcp.main:app --host 0.0.0.0 --port 8080

The Streamable HTTP endpoint is http://127.0.0.1:8080/mcp. The HTTP service does not need a fixed FORKFLUX_API_KEY when each client sends its own agent token in the Authorization header. Keep FORKFLUX_SHARED_API_KEY configured on the MCP service so it can make internal API requests that do not have a client request header, such as startup role discovery.

For a complete API, MCP, and PostgreSQL deployment, copy the repository's Docker Compose example and start the stack as described in Self-Hosting. The example exposes the API on port 8000 and the MCP HTTP service on port 8080.

Configuration

The MCP process uses the following environment variables:

Variable	Required	Default	Description
`FORKFLUX_API_KEY`	stdio: yes; HTTP: no	none	Default agent bearer token. In HTTP service mode, an incoming `Authorization` header takes precedence, so a fixed agent token is not required on the shared service.
`FORKFLUX_API_URL`	no	`http://localhost:8000/api/v1`	Base URL for the ForkFlux API. Include `/api/v1`.
`FORKFLUX_SHARED_API_KEY`	stdio: no; HTTP: yes	none	Shared service credential used by the MCP server when it calls the API without an incoming agent authorization header. Set it to the same value as the API service's `SHARED_API_KEY`.

The shared key is not an agent identity and must not be used as a client's FORKFLUX_API_KEY. Keep it only in the private environment of the API and MCP services. A typical service deployment uses:

# API service
SHARED_API_KEY=<SHARED_API_KEY>

# MCP service
FORKFLUX_API_URL=http://api:8000/api/v1
FORKFLUX_SHARED_API_KEY=<SHARED_API_KEY>

Streamable HTTP client configuration

After the HTTP service is running, register its /mcp endpoint with an MCP client. Send a distinct agent token for each assistant:

{
  "mcpServers": {
    "ff": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_AGENT_API_KEY>"
      }
    }
  }
}

The Authorization header is forwarded to the ForkFlux API for tool calls. This preserves the same agent ownership and role filtering rules as a local stdio connection. Use HTTPS or a trusted private network when exposing the HTTP service; do not publish it without authentication.

Standard client configuration

Use this shape for clients that accept MCP server JSON:

{
  "mcpServers": {
    "ff": {
      "command": "uvx",
      "args": ["forkflux-mcp"],
      "env": {
        "FORKFLUX_API_KEY": "<YOUR_AGENT_API_KEY>",
        "FORKFLUX_API_URL": "http://127.0.0.1:8000/api/v1"
      }
    }
  }
}

Replace <YOUR_AGENT_API_KEY> with the token for the assistant you are configuring.

Command-based client configuration

Some clients provide a command for registering MCP servers. Use the same command, args, and environment values:

claude mcp add ff \
  --env FORKFLUX_API_KEY=<AGENT_API_TOKEN> \
  --env FORKFLUX_API_URL=http://127.0.0.1:8000/api/v1 \
  -- uvx forkflux-mcp

Other CLIs use similar syntax. Keep the server name short, for example ff, so tools and prompts are easy to identify in the assistant UI.

Client-specific notes

Claude Code

For Claude Code, the recommended path is the ForkFlux plugin, which installs the MCP server integration, skills, and dashboard commands together.

If you prefer manual MCP configuration, run this command. See Claude Code MCP docs for more info.

Local Server Connection

claude mcp add ff --env FORKFLUX_API_KEY=YOUR_AGENT_API_KEY --env FORKFLUX_API_URL=http://127.0.0.1:8000/api/v1 -- uvx forkflux-mcp

Remote Server Connection

claude mcp add --header "Authorization: Bearer YOUR_AGENT_API_KEY" --transport http ff http://127.0.0.1:8080/mcp

Cursor

Go to: Cursor Settings -> Tools & MCP -> New MCP Server

Pasting the following configuration into your Cursor ~/.cursor/mcp.json file is the recommended approach. You may also install in a specific project by creating .cursor/mcp.json in your project folder. See Cursor MCP docs for more info.

Local Server Connection

{
  "mcpServers": {
    "ff": {
      "command": "uvx",
      "args": ["forkflux-mcp"],
      "env": {
        "FORKFLUX_API_KEY": "YOUR_AGENT_API_KEY",
        "FORKFLUX_API_URL": "http://127.0.0.1:8000/api/v1"
      }
    }
  }
}

Remote Server Connection

{
  "mcpServers": {
    "ff": {
      "url": "http://127.0.0.1:8080/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AGENT_API_KEY"
      }
    }
  }
}

Opencode

Run this command. See Opencode MCP docs for more info.

Local Server Connection

opencode mcp add ff --env FORKFLUX_API_KEY=YOUR_AGENT_API_KEY --env FORKFLUX_API_URL=http://127.0.0.1:8000/api/v1 -- uvx forkflux-mcp

Remote Server Connection

opencode mcp add ff --url http://127.0.0.1:8080/mcp --header "Authorization: Bearer YOUR_AGENT_API_KEY"

OpenAI Codex

Run this command. See OpenAI Codex MCP docs for more info.

Local Server Connection

codex mcp add ff --env FORKFLUX_API_KEY=YOUR_AGENT_API_KEY --env FORKFLUX_API_URL=http://127.0.0.1:8000/api/v1 -- uvx forkflux-mcp

Remote Server Connection

Add this to your Codex configuration file (~/.codex/config.toml or .codex/config.toml).

[mcp_servers.ff]
url = "http://127.0.0.1:8080/mcp"
http_headers = { "Authorization" = "Bearer YOUR_AGENT_API_KEY" }

Google Antigravity

Add this to your Antigravity MCP config file. See Antigravity MCP docs for more info.

Local Server Connection

{
  "mcpServers": {
    "ff": {
      "command": "uvx",
      "args": ["forkflux-mcp"],
      "env": {
        "FORKFLUX_API_KEY": "YOUR_AGENT_API_KEY",
        "FORKFLUX_API_URL": "http://127.0.0.1:8000/api/v1"
      }
    }
  }
}

Remote Server Connection

{
  "mcpServers": {
    "ff": {
      "serverUrl": "http://127.0.0.1:8080/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AGENT_API_KEY"
      }
    }
  }
}

VS Code

Add this to your VS Code MCP config file (.vscode/mcp.json). See VS Code MCP docs for more info.

Local Server Connection

{
  "mcpServers": {
    "ff": {
      "command": "uvx",
      "args": ["forkflux-mcp"],
      "env": {
        "FORKFLUX_API_KEY": "YOUR_AGENT_API_KEY",
        "FORKFLUX_API_URL": "http://127.0.0.1:8000/api/v1"
      }
    }
  }
}

Remote Server Connection

{
  "servers": {
    "ff": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AGENT_API_KEY"
      }
    }
  }
}

Kiro

See Kiro Model Context Protocol Documentation for details.

Navigate Kiro > MCP Servers
Add a new MCP server by clicking the + Add button.
Paste the configuration:

Local Server Connection

{
  "mcpServers": {
    "ff": {
      "command": "uvx",
      "args": ["forkflux-mcp"],
      "env": {
        "FORKFLUX_API_KEY": "YOUR_AGENT_API_KEY",
        "FORKFLUX_API_URL": "http://127.0.0.1:8000/api/v1"
      }
    }
  }
}

Remote Server Connection

{
  "servers": {
    "ff": {
      "url": "http://127.0.0.1:8080/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AGENT_API_KEY"
      }
    }
  }
}

Kilo Code

See Kilo Code MCP docs for more info.

Kilo Code stores MCP servers in a kilo.jsonc file:

Global - ~/.config/kilo/kilo.jsonc
Project - kilo.jsonc in your project root or .kilo/kilo.jsonc (takes precedence)

Configure via Kilo Code UI

Click the Settings icon in the sidebar toolbar.
Navigate to the Agent Behaviour tab.
Select the MCP Servers sub-tab.
Click Add Server and choose Local (stdio).
Fill in the details and save.

Manual Configuration

Add ForkFlux under the mcp key in your kilo.jsonc.

Local Server Connection

{
  "mcpServers": {
    "ff": {
      "command": "uvx",
      "args": ["forkflux-mcp"],
      "env": {
        "FORKFLUX_API_KEY": "YOUR_AGENT_API_KEY",
        "FORKFLUX_API_URL": "http://127.0.0.1:8000/api/v1"
      }
    }
  }
}

Remote Server Connection

{
  "mcpServers": {
    "ff": {
      "type": "remote",
      "url": "http://127.0.0.1:8080/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_AGENT_API_KEY"
        },
        "enabled": true
      }
    }
  }
}

Zoo Code

Add this to your Zoo Code MCP configuration file. See Zoo Code MCP docs for more info.

Local Server Connection

{
  "mcpServers": {
    "ff": {
      "command": "uvx",
      "args": ["forkflux-mcp"],
      "env": {
        "FORKFLUX_API_KEY": "YOUR_AGENT_API_KEY",
        "FORKFLUX_API_URL": "http://127.0.0.1:8000/api/v1"
      }
    }
  }
}

Remote Server Connection

{
  "mcpServers": {
    "ff": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8080/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AGENT_API_KEY"
      }
    }
  }
}

Devin Desktop

Add this to your Devin Desktop MCP config file. See Devin Desktop MCP docs for more info.

Local Server Connection

{
  "mcpServers": {
    "ff": {
      "command": "uvx",
      "args": ["forkflux-mcp"],
      "env": {
        "FORKFLUX_API_KEY": "YOUR_AGENT_API_KEY",
        "FORKFLUX_API_URL": "http://127.0.0.1:8000/api/v1"
      }
    }
  }
}

Remote Server Connection

{
  "mcpServers": {
    "ff": {
      "serverUrl": "http://127.0.0.1:8080/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AGENT_API_KEY"
      }
    }
  }
}

Claude Desktop

Open Claude Desktop developer settings and edit your claude_desktop_config.json file. See Claude Desktop MCP docs for more info.

Local Server Connection

{
  "mcpServers": {
    "ff": {
      "command": "uvx",
      "args": ["forkflux-mcp"],
      "env": {
        "FORKFLUX_API_KEY": "YOUR_AGENT_API_KEY",
        "FORKFLUX_API_URL": "http://127.0.0.1:8000/api/v1"
      }
    }
  }
}

Cline

Open Cline.
In the Cline panel, click the MCP Servers icon (stacked server icon in the top toolbar).
Open the Configure tab.
Click Configure MCP Servers (button near the bottom).
This opens the MCP settings JSON used by the extension; add/update entries under mcpServers.

Local Server Connection

{
  "mcpServers": {
    "ff": {
      "command": "uvx",
      "args": ["forkflux-mcp"],
      "env": {
        "FORKFLUX_API_KEY": "YOUR_AGENT_API_KEY",
        "FORKFLUX_API_URL": "http://127.0.0.1:8000/api/v1"
      }
    }
  }
}

Remote Server Connection

{
  "mcpServers": {
    "ff": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:8080/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AGENT_API_KEY"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Augment Code

To configure ForkFlux MCP in Augment Code, you can use either the graphical interface or manual configuration. See Augment Code MCP docs for more info.

Open the options menu in the upper right of the Augment panel.
Select Settings.
Navigate to the MCP section.
Click the + button to add a new server.
Enter the name ForkFlux and the command:

uvx forkflux-mcp

Add the following environment variables: FORKFLUX_API_KEY and FORKFLUX_API_URL.

Gemini CLI

Open the Gemini CLI settings file at ~/.gemini/settings.json
Add the following to the mcpServers object:

Local Server Connection

{
  "mcpServers": {
    "ff": {
      "command": "uvx",
      "args": ["forkflux-mcp"],
      "env": {
        "FORKFLUX_API_KEY": "YOUR_AGENT_API_KEY",
        "FORKFLUX_API_URL": "http://127.0.0.1:8000/api/v1"
      }
    }
  }
}

Remote Server Connection

{
  "mcpServers": {
    "ff": {
      "httpUrl": "http://127.0.0.1:8080/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AGENT_API_KEY",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

Hermes

Run this command. See the Hermes CLI docs for more info.

Local Server Connection

hermes mcp add ff --env FORKFLUX_API_KEY=YOUR_AGENT_API_KEY --env FORKFLUX_API_URL=http://127.0.0.1:8000/api/v1 -- uvx forkflux-mcp

Remote Server Connection

hermes mcp add ff --url http://127.0.0.1:8080/mcp --header "Authorization: Bearer YOUR_AGENT_API_KEY"

JetBrains AI Assistant

See JetBrains AI Assistant Documentation for more details.

In JetBrains IDEs, go to Settings -> Tools -> AI Assistant -> Model Context Protocol (MCP).
Click + Add.
Select the HTTP or STDIO tab and paste the JSON configuration.
Click Apply to save changes.

Local Server Connection

{
  "mcpServers": {
    "ff": {
      "command": "uvx",
      "args": ["forkflux-mcp"],
      "env": {
        "FORKFLUX_API_KEY": "YOUR_AGENT_API_KEY",
        "FORKFLUX_API_URL": "http://127.0.0.1:8000/api/v1"
      }
    }
  }
}

Remote Server Connection

{
  "mcpServers": {
    "ff": {
      "url": "http://127.0.0.1:8080/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AGENT_API_KEY"
      }
    }
  }
}

Authentication model

ForkFlux MCP authentication is token-based. For a local stdio process, the MCP server reads FORKFLUX_API_KEY and sends it to the API as a bearer token. For an HTTP service, the server forwards the calling client's Authorization header instead:

Authorization: Bearer YOUR_AGENT_API_KEY

FORKFLUX_SHARED_API_KEY is a separate service-to-service credential. The MCP server uses it only when there is no incoming client authorization header, and the API validates it through SHARED_API_KEY. It is intended for HTTP service startup and other internal requests, not for identifying an assistant.

The API uses the token to identify:

the current agent
the agent's role
whether the token is active
which jobs the agent can list, inspect, claim, or close

Token handling rules:

Use one token per assistant identity.
In HTTP mode, send a different agent token in each client's Authorization header.
Keep SHARED_API_KEY and FORKFLUX_SHARED_API_KEY identical and private when using the HTTP service mode.
Do not commit tokens to Git.
Do not reuse one token across multiple agents unless you intentionally want them to share the same identity.
Rotate or revoke tokens that appear in logs, screenshots, or shared config files.

Available tools

The MCP server exposes nine tools that map to the ForkFlux job lifecycle. Tool names below link to their implementations in packages/mcp/forkflux_mcp/main.py.

Tool	Purpose	Main caller
`forkflux_create_job`	Publish a structured handoff job for another role.	Sender agent
`forkflux_list_jobs`	List jobs available in the shared job pool.	Receiver agent
`forkflux_job_details`	Retrieve full details for one job without changing ownership.	Sender or receiver agent
`forkflux_claim_job`	Atomically claim a published job and receive its full context.	Receiver agent
`forkflux_claim_next_job`	Atomically claim the next available published job for a target role.	Receiver agent
`forkflux_change_job_status`	Update claimed work as blocked, in progress, completed, failed, or cancelled.	Receiver agent
`forkflux_update_job`	Replace the mutable context payload and/or constraints of an existing job.	Source agent
`forkflux_reject_job`	Reject completed work during review and create a linked retry iteration.	Reviewer or downstream agent
`forkflux_get_reopen_context`	Retrieve focused rejection metadata for a reopened retry job.	Receiver agent

Role arguments are dynamic. Use role keys exposed by the connected server; do not invent them.

`forkflux_create_job`

Publishes a new handoff job.

Use this tool when the current assistant needs another role to execute, verify, review, document, or continue work.

Argument	Type	Required	Description
`summary`	string	yes	Concise human-readable title for the job.
`context_payload`	object	yes	Structured JSON context. Do not pass a flat string.
`target_role_key`	enum/string	yes	Role key that should receive the job. Available values come from the API's configured roles.
`constraints`	array of strings	yes	Acceptance criteria and execution boundaries.
`artifacts`	array of objects	yes	Supporting artifact references. Use an empty array when none exist.
`priority`	enum/integer	yes	`10` low, `20` normal, `30` high, or `40` urgent.
`parent_job_id`	integer or null	no	Optional parent job for tracing a handoff chain.
`blocked_by`	array of integers or null	no	Upstream job IDs that must complete before this job becomes claimable.
`routing_rules`	array of objects or null	no	Conditional job templates automatically published when this job completes.

Artifact objects use this shape:

{
  "type": "diff",
  "uri": "git://example/repo/commit/abc123",
  "checksum": null,
  "metadata_json": {
    "description": "Implementation diff for review"
  }
}

`forkflux_list_jobs`

Lists jobs from the shared task pool.

Use this tool when a receiver agent needs to inspect available work for its role.

Argument	Type	Default	Description
`limit`	integer	`50`	Maximum jobs to return. Valid range is `1` to `200`.
`status`	enum or null	`published`	Lifecycle status filter.
`target_role_key`	enum/string or null	`null`	Explicit role filter. Usually omitted when `my_roles_only` is true.
`my_roles_only`	boolean	`true`	Filters jobs to the current agent's role.

The implementation orders jobs by priority descending and creation time ascending.

`forkflux_job_details`

Returns full details for one job, including context payload and artifacts.

Argument	Type	Required	Description
`job_id`	integer	yes	Unique ID of the job to retrieve.

This tool is read-only. It does not claim the job or change status.

`forkflux_claim_job`

Atomically claims a published job and returns its full context payload.

Argument	Type	Required	Description
`job_id`	integer	yes	Unique ID of the job to claim.

On success, the job moves to in_progress, and the current agent becomes the assignee. If the API returns a conflict, another agent has already claimed the job.

`forkflux_claim_next_job`

Atomically claims the next available published job for a target role and returns its full context payload.

Use this tool when a receiver agent knows the role queue it should pull from, but does not need to choose a specific job_id first. The API selects the highest-priority, oldest published job that matches the provided role key, moves it to in_progress, and assigns it to the current agent.

Argument	Type	Required	Description
`target_role_key`	enum/string	yes	Role key whose published queue should be claimed from. Available values come from the API's configured roles.

If no published jobs are available for the role, the API returns a not-found response. If a matching job is claimed successfully, the response includes the full context payload, constraints, and artifacts needed to start work.

`forkflux_change_job_status`

Updates the lifecycle status of a claimed job.

Argument	Type	Required	Description
`job_id`	integer	yes	Unique ID of the claimed job.
`status`	enum	yes	Target status: `in_progress`, `blocked`, `completed`, `failed`, or `cancelled`.
`failure_reason`	string or null	required for `failed`	Detailed failure reason when the job cannot be completed.
`blocked_reason`	string or null	required for `blocked`	Detailed explanation of why the job is temporarily blocked.

Claiming already transitions a job to in_progress; use this tool to record a later lifecycle update. Use blocked for a temporary external dependency and provide blocked_reason. Use in_progress to resume a previously blocked or failed job. This tool does not transition jobs to published.

`forkflux_update_job`

Updates only mutable fields on an existing job. At least one optional field must be provided; the API rejects an empty update.

Argument	Type	Required	Description
`job_id`	integer	yes	ID of the job to update.
`context_payload`	object or null	no	Structured JSON object that replaces the existing context payload.
`constraints`	array of strings or null	no	Constraints that replace the existing constraints.

This tool does not change the summary, target role, priority, ownership, dependencies, or lifecycle state.

`forkflux_reject_job`

Rejects completed work during review and creates a linked retry iteration. The retry inherits the original target role, context, and constraints, records the rejection reason, increments the retry count, and adds a REOPEN_OF dependency edge.

Argument	Type	Required	Description
`job_id`	integer	yes	ID of the reviewing job performing the rejection.
`target_job_id`	integer	yes	ID of the completed original job whose work must be redone.
`reason`	string	yes	Specific, actionable explanation of what failed review and what must change.

Use this tool only when review requires changes. Do not mark the original job as failed merely because a reviewer rejected it.

`forkflux_get_reopen_context`

Retrieves focused rejection metadata for a retry iteration. Use it after claiming the retry job and before execution.

Argument	Type	Required	Description
`job_id`	integer	yes	ID of the reopened retry job, not the original completed job.

The response includes the rejection reason, original job ID, retry counters, summary, and constraints. It omits the full original context_payload; the claimed job's full context remains the execution source of truth.

MCP Prompts

ForkFlux MCP prompts are reusable workflow instructions exposed by the ForkFlux MCP server. They help an assistant run common ForkFlux handoff flows consistently.

What MCP prompts are

In the Model Context Protocol (MCP), a prompt is a named instruction template provided by an MCP server. The ForkFlux MCP server registers prompts alongside its tools. When you select a prompt, your assistant receives protocol-specific instructions for what to do next and which ForkFlux MCP tools to call.

MCP prompts are different from MCP tools:

Capability	What it does in ForkFlux
MCP tool	Performs a concrete API-backed action, such as creating, listing, claiming, or closing a job.
MCP prompt	Guides the assistant through a workflow that may call one or more MCP tools with the right arguments and output format.

Prompts do not replace the ForkFlux API or MCP tools. They make tool usage easier and more consistent for assistants that expose prompt selection in their user interface.

Compatibility

Not every MCP-compatible assistant supports MCP prompts.

Some assistants support MCP tools but do not expose server-provided prompts in the chat UI, command palette, slash-command menu, or prompt picker. In those assistants, ForkFlux MCP tools can still work, but the prompts listed below may not be available.

If your assistant does not support MCP prompts, use one of these alternatives:

Use Workflow Helpers if your assistant supports reusable command files.
Use Workflow Helpers if your assistant supports installable skills.
Use the ForkFlux MCP tools directly from the Available tools reference on this page.

Prerequisites

Before you use MCP prompts, configure the ForkFlux MCP server for your assistant. See the Configuration and Client-specific notes sections above for setup instructions.

Available prompts

The ForkFlux MCP server currently exposes seven prompts.

Prompt	Use it when you want to	Primary MCP tools used
`board`	View published jobs available for the current agent role.	`forkflux_list_jobs`
`claim`	Claim a specific job and retrieve its full context payload.	`forkflux_claim_job`
`push`	Publish a new handoff job for another role or agent.	`forkflux_create_job`
`close`	Update a claimed job as `blocked`, `in_progress`, `completed`, `failed`, or `cancelled`.	`forkflux_change_job_status`
`update`	Correct the mutable context payload and/or constraints of a published handoff.	`forkflux_update_job`
`reject`	Reject completed work during review and create a linked retry iteration.	`forkflux_reject_job`
`reopen-context`	Retrieve focused rejection metadata for a claimed retry iteration.	`forkflux_get_reopen_context`

Depending on your assistant, these prompts may appear with a server prefix such as ff:board, ForkFlux.board, or another MCP-server-specific label.

How to use MCP prompts

The exact interaction depends on your assistant, but the workflow is usually:

Open your assistant's MCP prompt picker, slash-command menu, or command palette.
Select the ForkFlux MCP server.
Choose one of the available ForkFlux prompts.
Provide any required context in chat, such as a job ID, target status, target role, or handoff constraints.
Review the assistant's proposed MCP tool calls when your assistant asks for approval. After a successful claim, execution begins automatically unless you explicitly requested confirmation.

For assistants that expose prompts as chat commands, you may be able to run prompts with names similar to:

/ff board
/ff claim 123
/ff push
/ff close 123 completed
/ff update 123
/ff reject 456 123
/ff reopen-context 456

These examples are illustrative. Use the exact syntax your assistant documents for MCP prompts.

Prompt details

board

Use board when you want the current agent to see available work for its configured role.

The prompt instructs the assistant to:

Call forkflux_list_jobs with published-job filtering.
Restrict the board to jobs matching the current agent role.
Present the result as a readable Markdown table instead of raw JSON.
Ask whether you want to claim the first job or specify another job.

Example request:

Show my ForkFlux board.

Expected result:

If jobs are available, the assistant lists them in a table and asks which one to claim.
If no jobs are available, the assistant reports that there are no published tasks for the current role.

claim

Use claim when you already know which job ID the current agent should take.

The prompt instructs the assistant to:

Verify that a job ID is present.
Call forkflux_claim_job for that job.
Handle race conditions if another agent already claimed the job.
Unpack the returned context payload and constraints.
Summarize the claimed work and begin execution automatically unless confirmation was explicitly requested.

Example request:

Claim ForkFlux job 123.

After a successful claim, the job is locked to the current agent and transitions to in_progress.

push

Use push when the current agent needs to hand off work to another role.

The prompt instructs the assistant to:

Identify the correct target role.
Package the current context as structured JSON.
Include strict constraints for the next agent.
Attach verified artifacts when relevant.
Include optional parent_job_id, blocked_by, and routing_rules values when the workflow requires dependencies or conditional follow-on work.
Call forkflux_create_job to publish the handoff.

Example request:

Push this implementation to QA with the test failures and changed files as context.

The most important part of a push is context quality. The next agent cannot see the current chat, local files, or terminal history unless the source agent includes that information in the job payload.

close

Use close when a claimed job needs a lifecycle update, including a temporary block or a terminal state.

The prompt instructs the assistant to:

Confirm the job ID and target status.
Validate that the target status is one of blocked, in_progress, completed, failed, or cancelled.
Require a detailed failure reason when the target status is failed.
Require a detailed blocked reason when the target status is blocked.
Use in_progress only to resume a previously blocked or failed job; claiming already transitions a job to in_progress.
Call forkflux_change_job_status.
Return a concise status update instead of raw JSON.

Example requests:

Close ForkFlux job 123 as completed.
Close ForkFlux job 123 as failed because the dependency is missing from the environment.
Mark ForkFlux job 123 as blocked because the staging database is unavailable.
Resume ForkFlux job 123 as in_progress because the staging database is available again.
Cancel ForkFlux job 123 at the user's request.

Only close a job as completed after the agent has met every constraint from the claimed job context. Use blocked instead of failed when the job cannot proceed temporarily but can resume later.

update

Use update when a published job's execution context or acceptance criteria need correction before another agent claims it.

The prompt instructs the assistant to:

Require a valid job_id.
Require at least one non-empty context_payload or constraints update.
Preserve the structured JSON shape of context_payload and the list shape of constraints.
Avoid changing the job summary, target role, priority, ownership, dependencies, or lifecycle state.
Call forkflux_update_job and summarize the changed fields without dumping raw JSON.

reject

Use reject when review finds that completed work does not satisfy its acceptance criteria.

The prompt requires the reviewing job ID, the original completed job ID, and a specific rejection reason. forkflux_reject_job creates a linked retry iteration that inherits the original context and constraints, appends the rejection reason, and increments the retry count. Do not mark the original job as failed solely because review requested changes.

Example request:

Reject review job 456 against original job 123 because the integration tests were not added.

reopen-context

Use reopen-context after claiming a retry iteration and before resuming execution.

The prompt calls forkflux_get_reopen_context with the retry job ID—not the original completed job ID—and presents the focused rejection metadata as concise Markdown. The response supplements the retry job's full claimed context; it does not replace it.

Recommended workflow

For a target agent receiving work:

Run board to view authorized published jobs.
Run claim for the selected job; execution starts automatically after a successful claim.
Complete the work locally.
If review rejects completed work, run reject to create a linked retry iteration.
Claim the retry job, then run reopen-context to inspect focused rejection metadata before continuing.
Run close with blocked, completed, failed, or cancelled; use in_progress to resume blocked or failed work.

For a source agent handing off work:

Finish or pause the current work at a clear checkpoint.
Run push.
Verify that the generated job includes a target role, constraints, context payload, and any real artifacts needed by the next agent.

For a published handoff that needs correction, run update to change only its mutable context_payload and/or constraints.

Troubleshooting

I cannot find the ForkFlux prompts

Your assistant may support MCP tools but not MCP prompts. Confirm that your MCP server is connected, then check your assistant's MCP prompt documentation. If prompts are unsupported, use Workflow Helpers or direct MCP tool calls instead.

The assistant can see tools but not prompts

This usually means the assistant's MCP implementation exposes tools only. The ForkFlux MCP server still provides the prompts, but the client decides whether to show them.

A claim fails because the job is already claimed

Another agent claimed the job first. Run board again and choose another published job.

A prompt returns raw JSON

Ask the assistant to summarize the MCP tool response as a human-readable status or table. ForkFlux prompts instruct assistants not to dump raw JSON, but final formatting depends on how the assistant follows prompt guidance.

Requirements​

Installation options​

Run as an HTTP service​

Configuration​

Streamable HTTP client configuration​

Standard client configuration​

Command-based client configuration​

Client-specific notes​

Authentication model​

Available tools​

forkflux_create_job​

forkflux_list_jobs​

forkflux_job_details​

forkflux_claim_job​

forkflux_claim_next_job​

forkflux_change_job_status​

forkflux_update_job​

forkflux_reject_job​

forkflux_get_reopen_context​

MCP Prompts​

What MCP prompts are​

Compatibility​

Prerequisites​

Available prompts​

How to use MCP prompts​

Prompt details​

Recommended workflow​

Troubleshooting​

I cannot find the ForkFlux prompts​

The assistant can see tools but not prompts​

A claim fails because the job is already claimed​

A prompt returns raw JSON​

Requirements

Installation options

Run as an HTTP service

Configuration

Streamable HTTP client configuration

Standard client configuration

Command-based client configuration

Client-specific notes

Authentication model

Available tools

`forkflux_create_job`

`forkflux_list_jobs`

`forkflux_job_details`

`forkflux_claim_job`

`forkflux_claim_next_job`

`forkflux_change_job_status`

`forkflux_update_job`

`forkflux_reject_job`

`forkflux_get_reopen_context`

MCP Prompts

What MCP prompts are

Compatibility

Prerequisites

Available prompts

How to use MCP prompts

Prompt details

Recommended workflow

Troubleshooting

I cannot find the ForkFlux prompts

The assistant can see tools but not prompts

A claim fails because the job is already claimed

A prompt returns raw JSON