forkflux-mcp — Claude Code MCP server: hand off work between agents
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.
claude mcp add --env FORKFLUX_API_KEY=<FORKFLUX_API_KEY> --env FORKFLUX_API_URL=<FORKFLUX_API_URL> --transport stdio mcp -- uvx forkflux-mcpWhat forkflux-mcp 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.
What it helps with
- 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 for the agent
- 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
How to install forkflux-mcp
Platform CLI
claude mcp add --env FORKFLUX_API_KEY=<FORKFLUX_API_KEY> --env FORKFLUX_API_URL=<FORKFLUX_API_URL> --transport stdio mcp -- uvx forkflux-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from forkflux-mcp <command>
Platform CLI
codex mcp add mcp --env FORKFLUX_API_KEY=<FORKFLUX_API_KEY> --env FORKFLUX_API_URL=<FORKFLUX_API_URL> -- uvx forkflux-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from forkflux-mcp <command>
Config file
{
"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>
Config file
{
"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>
Platform CLI
gemini mcp add -e FORKFLUX_API_KEY=<FORKFLUX_API_KEY> -e FORKFLUX_API_URL=<FORKFLUX_API_URL> mcp uvx forkflux-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from forkflux-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about forkflux-mcp
How do I install forkflux-mcp in Claude Code?
Run claude mcp add forkflux-mcp -e FORKFLUX_API_KEY=<FORKFLUX_API_KEY> -- uvx forkflux-mcp. Alternatively use claude mcp add --env FORKFLUX_API_KEY=<FORKFLUX_API_KEY> --env FORKFLUX_API_URL=<FORKFLUX_API_URL> --transport stdio mcp -- uvx forkflux-mcp.
What does forkflux-mcp do?
It gives an assistant tools to publish jobs, claim them, change their status and reject finished work with a retry. Everything goes through your self-hosted ForkFlux API, which holds agents, roles and dependencies.
How is HTTP mode different from stdio?
With stdio each client spawns its own process and passes FORKFLUX_API_KEY. HTTP mode runs one long-lived service via uvicorn forkflux_mcp.main:app, and clients send their own token in the Authorization: Bearer <AGENT_API_TOKEN> header.
