# forkflux-mcp

Wires MCP-compatible assistants to your self-hosted ForkFlux API so agents can publish jobs, claim them and keep an audit trail of each handoff.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 6
- Author: forkflux
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/forkflux/forkflux/tree/HEAD/packages/mcp
- Updated: 2026-08-11
- HTML: https://affpapa.org/en/nevibecode/mcp/forkflux-mcp

## What it does

ForkFlux MCP sits between an MCP-compatible assistant and your own ForkFlux API instance. One agent publishes a structured job carrying context, constraints, artifacts, priority and a target role; another agent claims it atomically and gets the whole payload back. From there the job moves through `blocked`, `in_progress`, `completed`, `failed` or `cancelled`.

Nine tools ship in the package. `forkflux_create_job` and `forkflux_list_jobs` handle publishing and listing, `forkflux_claim_job` and `forkflux_claim_next_job` do the atomic grab, while `forkflux_job_details` and `forkflux_update_job` read and revise the context. Rounding it out: `forkflux_reject_job` opens a linked retry job with the rejection reason attached, and `forkflux_get_reopen_context` returns just the retry context instead of reloading the original payload.

The server keeps no state of its own. It prefixes API calls with `/mcp`, authenticates them with the calling agent's bearer token or a shared service credential when no client header arrives, and hands back structured success or error results. Agents, roles, dependencies and lifecycle events live in the API, which stays the source of truth. You need Python 3.12+ and a running ForkFlux API endpoint; over stdio the agent's API key is required.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `FORKFLUX_API_KEY`, `FORKFLUX_API_URL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env FORKFLUX_API_KEY=<FORKFLUX_API_KEY> --env FORKFLUX_API_URL=<FORKFLUX_API_URL> --transport stdio mcp -- uvx forkflux-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from forkflux-mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add mcp --env FORKFLUX_API_KEY=<FORKFLUX_API_KEY> --env FORKFLUX_API_URL=<FORKFLUX_API_URL> -- uvx forkflux-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from forkflux-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "mcp": {
            "command": "uvx",
            "args": [
                "forkflux-mcp"
            ],
            "env": {
                "FORKFLUX_API_KEY": "<FORKFLUX_API_KEY>",
                "FORKFLUX_API_URL": "<FORKFLUX_API_URL>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from forkflux-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "mcp": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "forkflux-mcp"
            ],
            "env": {
                "FORKFLUX_API_KEY": "<FORKFLUX_API_KEY>",
                "FORKFLUX_API_URL": "<FORKFLUX_API_URL>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from forkflux-mcp <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e FORKFLUX_API_KEY=<FORKFLUX_API_KEY> -e FORKFLUX_API_URL=<FORKFLUX_API_URL> mcp uvx forkflux-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from forkflux-mcp <command>

## When to use it
- hand a task to another agent without pasting logs around
- record a rejection and spin up a linked retry job
- pull the highest-priority open job for a given role
- correct the context of a job that is already published
- run one shared MCP service for several assistants

## Example prompts
- Publish a job for the reviewer role with the context and artifacts from the last commit
- Claim the next highest-priority job for my role
- Show the job details and move it to `in_progress`

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md