@resolflow/mcp-client
v2.1.0
Published
Resolflow MCP client - stdio to HTTP bridge for AI assistants (Claude Desktop, Cursor, VS Code, Zed, Windsurf)
Maintainers
Readme
Resolflow MCP Client
stdio-to-HTTP bridge that allows AI assistants to connect to the Resolflow MCP server.
This package provides seamless integration between stdio-based AI clients (Claude Desktop/Code, ChatGPT Codex, VS Code/GitHub Copilot, Cursor, Gemini Antigravity) and Resolflow's HTTP-based MCP server.
What This Does
Resolflow MCP server runs over HTTP, but AI clients (Agents, Applications/Tools) like Claude Desktop expect stdin/stdout communication. This client bridges that gap:
AI Client (stdio) <---> resolflow-mcp <---> Resolflow Server (HTTPS)Key Features:
- ✅ Auto-discovery: Token automatically identifies your project (no project_id needed)
- ✅ Zero configuration: Works out of the box with npx
- ✅ Retry logic: Automatic retries on transient errors (429, 5xx, network). Tool calls are only retried on 429 or connection failures, so a retry never duplicates a write
- ✅ Secure: Token-based authentication over HTTPS
- ✅ Standard protocol: JSON-RPC 2.0 / MCP compliant
- ✅ Multi-IDE support: Claude Desktop, VS Code, Cursor, Windsurf, Zed, and more
Quick Start
With npx (No installation needed)
RESOLFLOW_MCP_TOKEN=YOUR_TOKEN npx @resolflow/mcp-client--token YOUR_TOKEN still works but prints a warning: a command-line flag is visible in the process list and shell history.
Claude Desktop Configuration
Edit your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"resolflow": {
"command": "npx",
"args": ["-y", "@resolflow/mcp-client"],
"env": { "RESOLFLOW_MCP_TOKEN": "YOUR_TOKEN_HERE" }
}
}
}Restart Claude Desktop. Resolflow tools will be automatically available.
VS Code / GitHub Copilot
Method 1: MCP Extension
- Press
Ctrl/Cmd + Shift + P - Type:
MCP: Add Server - Select:
Command (stdio) - Enter:
npx @resolflow/mcp-clientand setRESOLFLOW_MCP_TOKENin the server env (or use Method 2) - Name:
Resolflow
Method 2: mcp.json
Add to .vscode/mcp.json:
{
"servers": {
"resolflow": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@resolflow/mcp-client"],
"env": { "RESOLFLOW_MCP_TOKEN": "YOUR_TOKEN_HERE" }
}
}
}Cursor
Add to Cursor settings or .cursor/mcp.json:
{
"mcpServers": {
"resolflow": {
"command": "npx",
"args": ["-y", "@resolflow/mcp-client"],
"env": { "RESOLFLOW_MCP_TOKEN": "YOUR_TOKEN" }
}
}
}Windsurf
- Press
Ctrl/Cmd + ,(Settings) - Navigate to: Cascade → MCP servers
- Click: Add Server → Add custom server
- Paste:
{
"mcpServers": {
"resolflow": {
"command": "npx",
"args": ["-y", "@resolflow/mcp-client"],
"env": { "RESOLFLOW_MCP_TOKEN": "YOUR_TOKEN" }
}
}
}Zed
- Press
Cmd + ,(Settings) - Add:
{
"context_servers": {
"resolflow": {
"source": "custom",
"command": "npx",
"args": ["-y", "@resolflow/mcp-client"],
"env": { "RESOLFLOW_MCP_TOKEN": "YOUR_TOKEN" }
}
}
}Claude Code
claude mcp add resolflow -e RESOLFLOW_MCP_TOKEN=YOUR_TOKEN -- npx -y @resolflow/mcp-clientThen run /mcp in Claude Code to confirm the server is connected.
Other MCP-Compatible Clients
Command: npx
Arguments: -y @resolflow/mcp-client
Environment: RESOLFLOW_MCP_TOKEN=YOUR_TOKEN
Wake an agent when work arrives (watch)
Since 1.2, resolflow-mcp watch checks the queue of a token (get_my_queue: stages to work, stages to review, tasks delegated to it) and runs a command for each new item, one at a time. The item is in the environment of the command: RESOLFLOW_TASK_ID, RESOLFLOW_ITEM_KIND (work, review, deploy, suggest or rework), RESOLFLOW_DEPLOYMENT_ID (deploy items) and RESOLFLOW_ITEM (JSON).
Since 2.0, --exec does not use a shell. The command is split into words (single quotes, double quotes and backslash group words, nothing else) and started directly. $, |, ;, &&, backticks, $(...) and globs are plain text, so text from the server can never become a command. In the arguments, watch replaces only $RESOLFLOW_TASK_ID, $RESOLFLOW_DEPLOYMENT_ID (each must be a UUID) and $RESOLFLOW_ITEM_KIND (one of the kinds above); when a value is missing or malformed, the item is skipped and nothing runs. $RESOLFLOW_ITEM is never put into the command line (it contains text people wrote): read it from the environment in your program, or let the agent call get_my_queue.
Since 1.3, finished deploys come too: when a staging or production deploy of tasks the agent works (or its team works, for the lead) succeeds or fails, a deploy item arrives with the environment, outcome, run URL, the tasks and the next step (RESOLFLOW_DEPLOYMENT_ID is set). It stays until the agent calls ack_message with its message_id, or 48 hours. The project chooses which deploys are sent in Releases & deployments → Configuration.
New tasks: propose the description and todos (--kinds suggest). A team lead (orchestrator token) or a single agent (role all, no team) can watch for tasks a person just created that still need a description or todos. While it polls with --kinds suggest Resolflow counts it as watching (2 minutes); each new task arrives as a suggest item with needs (description, todos, more_todos, check_todos), the existing todos and a recommended_model_tier. The agent calls claim_suggest (first caller wins for 10 minutes, so two agents never propose and the cloud Task Planner review is skipped), reads the task, then suggest_task_details. The proposal is stored as a suggestion people accept item by item in Resolflow; it never changes the task or its todos. A lead can do it itself or hand it to a sub agent with delegate_task (kind: "suggest", model): pick a model of at least the recommended tier — Resolflow warns when it is below. Sub agents get a suggest item only when their lead delegates one. Without a watching lead or single agent the cloud review runs as before. Suggest items are opt-in: don't pass --kinds suggest and none arrive.
Reopened tasks (since 2.1). When a person reopens a finished task ("Request rework", with a reason and a stage), the agent working it gets a work item again with reopened: true, round (the how-many-th reopen), revision_todo_id and the reason in returned_reason; it works the revision todo first, then hands the stage in again. Each reopen is a new item, even at the same stage, so --exec runs once per reopen. The team lead gets a rework item until it delegates the task with delegate_task (or someone claims it); --kinds suggest includes rework, and --kinds suggest,rework says so explicitly. The reason is text a person wrote: it is in RESOLFLOW_ITEM and get_inbox (task.reopened), never in the command line. Clients before 2.1 drop rework items when --kinds suggest is set (the inbox message still arrives).
# A team lead (or a single agent) that proposes the description and todos of new tasks
# and delegates tasks a person reopened
RESOLFLOW_MCP_TOKEN=LEAD_TOKEN npx -y @resolflow/mcp-client watch --kinds suggest,rework \
--exec 'claude -p "Làm item Resolflow $RESOLFLOW_TASK_ID: gọi get_my_queue"'
# A reviewer agent that runs Claude Code headless whenever a stage waits for its review
RESOLFLOW_MCP_TOKEN=REVIEWER_TOKEN npx -y @resolflow/mcp-client watch \
--exec 'claude -p "Review the Resolflow task $RESOLFLOW_TASK_ID: claim_review, check the work, submit_review."'
# Wake up only when a deploy of your tasks finished
RESOLFLOW_MCP_TOKEN=YOUR_TOKEN npx -y @resolflow/mcp-client watch --kinds deploy \
--exec 'claude -p "Deploy $RESOLFLOW_DEPLOYMENT_ID của task $RESOLFLOW_TASK_ID đã xong: gọi get_my_queue, làm next_step rồi ack_message"'
# Just print new work (and ring the terminal bell)
RESOLFLOW_MCP_TOKEN=YOUR_TOKEN npx -y @resolflow/mcp-client watch| Option | |
|---|---|
| --exec <command> | Command to run per new item, without a shell (see above) |
| --exec-shell <command> | 1.x behaviour: run the command through your shell. Opt-in, prints a warning on every run, cannot be combined with --exec. Required for Windows .cmd / .bat |
| --interval <sec> | Seconds between checks (default 30, minimum 10) |
| --skip-existing | Ignore what is already in the queue at start |
| --once | Check once and exit |
| --kinds <list> | Only these items: work, review, deploy, suggest, rework (comma separated). suggest is opt-in and brings rework too |
Migrating from 1.x
2.0 is a security release with breaking changes for watch and the server URL:
--execno longer runs through a shell. Pipes,;,&&, redirects,$(...), backticks, globs and$OTHER_VARSare not interpreted any more. If you need them, put them in a script and run the script (--exec './on-item.sh', reading$RESOLFLOW_*from the environment), or switch to--exec-shell(the 1.x behaviour, with a warning on every run).$RESOLFLOW_ITEMis no longer substituted into the command line. Prompts that put the item JSON into the command line become, for example,claude -p "Làm item Resolflow $RESOLFLOW_TASK_ID: gọi get_my_queue"; the agent reads the item itself. A command that contains$RESOLFLOW_ITEMis refused at start. Other$RESOLFLOW_*names (except the three above) are refused too.- Variables are checked.
$RESOLFLOW_TASK_ID/$RESOLFLOW_DEPLOYMENT_IDmust be UUIDs and$RESOLFLOW_ITEM_KINDa known kind, or the item is skipped. - Windows:
.cmd/.bat(including npm shims such asclaude.cmd) need--exec-shell; cmd.exe expands%VAR%, so keep server text out of the command. http://to a non-loopback host is refused; usehttps://or add--insecure-http.--tokenprints a warning; move the token toRESOLFLOW_MCP_TOKEN(MCP client configs: theenvblock).- Text from the server (titles, next steps, errors) is printed with terminal control characters and escape sequences removed.
Getting Your Token
- Go to resolflow.ai → Projects → Your Project
- Navigate to Settings → MCP Tokens
- Click Generate Token
- Copy the token
Options
RESOLFLOW_MCP_TOKEN=<token> resolflow-mcp [--url <url>]| Option | Description | Default |
|--------|-------------|---------|
| --token | Authentication token (prefer RESOLFLOW_MCP_TOKEN; the flag prints a warning) | — |
| --url | Server URL (also RESOLFLOW_MCP_URL). https://, or http:// to this machine (localhost, 127.x, ::1) | https://api.resolflow.ai/api/mcp |
| --insecure-http | Allow http:// to another host (the token travels unencrypted) | — |
| --version, -v | Print version | — |
| --help, -h | Show help | — |
Environment Variables
export RESOLFLOW_MCP_TOKEN="your-token"
resolflow-mcpAvailable Tools
Tools are served by the Resolflow MCP server and discovered automatically via tools/list, so new server-side tools work without upgrading this client. Current tools:
Project
get_project_context- Project details, guardrails and workspace infolist_project_documents/store_project_document- Read and store project documents
Session context (memory between sessions)
save_context- Save markdown notes under a key for your later sessions (scopeproject,taskorteam; 64 KB max; expires 14 days after its last use)get_context,list_contexts- Pick up saved context at the start of a sessiondelete_context- Remove an entry that is no longer true
Tasks
list_tasks,get_task_by_id,search_tasks- Browse and look up taskscreate_task- Create new tasksupdate_task- Fix a task's title, description or priority instead of creating a duplicate (lead / single agent tokens only; never status, stage, type, groups or assignee). Passexpected_updated_at(theupdatedAtyou read): a task changed meanwhile answers 409 with its current values. Refused while a stage waits for review and on done / cancelled tasks; every edit is kept as old → new in the historyget_unclaimed_tasks- Find open tasks nobody has claimed (drafts are parked by humans; passstatus: "draft"to list them)claim_task- Claim a task (auto-assignment,forceto override)cancel_task- Cancel a task with a reason. Applied right away only for an agent-created task nobody has started; otherwise a project Owner/PO/PM approves it in Resolflowrequest_task_deletion- Ask an Owner/PO/PM to delete a task. Agents never delete directly, and tasks with completed work can't be deleted
Epics, sprints & user stories
create_task_group- Create an epic, sprint (with dates) or custom grouplist_task_groups- List groups with their task countsassign_task_to_groups- Move a task into or out of an epic, sprint or custom groupscreate_user_story- Create a user story ("As a … I want … so that …" + acceptance criteria)
Releases
create_release- Record a release: version, name, link (tag / PR / pipeline), commit and the tasks it shipslist_releases,get_release- Releases with status, dates, tasks, notes and historyadd_tasks_to_release- Link tasks to a releaseupdate_release_status- Recordplanned→in_staging→released→verified, orrolled_back, with a note (deploy link, checks, incident). A rollback can name the release live again (rolled_back_to_release_id, default: the previous one) and notifies the teamgenerate_release_notes- Build release notes from the linked tasks, grouped by typerequest_deploy- Ask to promote staging to production or roll production back through the team's own CI (pipeline control). A person other than you approves first, unless the project approves automatically
Todos
list_todos,get_todo_by_id,search_todos- Browse and look up todoscreate_todo,bulk_create_todos- Create todos. Write the description asWHAT:/CHANGE:/FILES:/ACCEPTANCE:sections, each label on its own line followed by-bullet lines (real line breaks), and pass the checks asacceptance_criteria[]andvalidation_steps[](alsoestimated_minutes,priority)claim_todo- Claim a todoupdate_todo- Fix a todo's title, description, priority,acceptance_criteria,validation_stepsorestimated_minutes(never its status). Lead / single agent tokens: any todo of the project; coder / tester tokens: todos of a task delegated to them; reviewers: none. A done todo keeps its criteria and steps. Sameexpected_updated_at, 409 and history rules asupdate_task; at most 120 edits an hour per tokenupdate_todo_status- Update progresspost_todo_artifact- Attach artifacts
Orchestration
ask_orchestrator- Get AI guidancereport_loop_signal- Report loop signalsget_inbox,ack_message,dismiss_message- Orchestrator messagespost_status_update- Lead tokens only (roleorchestratororall): tell the project's people on the web what happened (a card or the floating agent bubble on any page). Markdownbody(≤ 2000), optionaltitle(≤ 120),kind(info|progress|done|warning|needs_you),task_id, up to 3links(https or app paths) and athreadkey that updates the same update in place (progress → done). Post at meaningful moments only (a merge, a deploy started/finished, a stage handed in or returned, a blocker, a decision you need), never every step and never secrets (refused with 422). At most 6 in 10 minutes and 30 an hour per token; the same content within 10 minutes is not posted twicerequest_release_merge- Lead tokens only: ask the people who approve deploys to review and merge a release PR (dev → main) of the project's connected repository. Passpr_number(orpr_url, read only for its repository and number), optionallyintegration_id,release_version, a plain-textsummary(≤ 280),task_idsandstaging_verified. The server checks the PR through GitHub / GitLab (open, not a draft, not a fork, into the default branch) and shows a dialog with CI, staging, migrations, conflicts, the expected version and the tasks, plus a button to the PR whose URL the server builds. One request per PR (calling again updates it); it follows the PR until merged or closed. At most 6 an hour per token. Resolflow never merges, and agents must never merge it themselves
Workflows, templates & reports
list_workflows,get_workflow- Workflow definitionssuggest_template,apply_template- Task templateslist_reports,get_report- Reports
Development
# Install
cd mcp-client
pnpm install
# Build
pnpm run build
# Test locally
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | RESOLFLOW_MCP_TOKEN=YOUR_TOKEN node dist/index.jsTroubleshooting
"Unauthorized - invalid or expired token"
- Verify your token is correct and hasn't been revoked
- Generate a new token from the Resolflow dashboard
"Connection refused" / network errors
- The client will automatically retry up to 3 times on transient errors (tool calls are retried only on 429 or connection failures)
- Check your internet connection and firewall settings
License
MIT
