SwipeFlow MCP Server

Human-in-the-loop approvals for AI agents, over the Model Context Protocol.

An agent asks a person to review something, gets a durable handle back, and resumes once a decision has been made. Human review takes minutes or days, so the wait is asynchronous by design — the agent is never required to hold a connection open.

Status: early development. The tool surface is being built against MCP 2026-07-28. Not yet ready for production use.

Why this exists

Agents increasingly produce work that a human should approve before it ships — content, code changes, outbound messages, spending decisions. The awkward part is never the approval itself, it's the waiting: humans are slow and agents are not built to block.

This server makes that wait a first-class protocol concern.

Related MCP server: QMCP

Design

Three properties shape everything else:

Stateless. The server holds no task store, no session store, no database. Task state lives in SwipeFlow, because a review is a task. That is what gives resumability across restarts, horizontal scaling with no coordination, and self-hosting with no infrastructure.

Decisions are outcomes, not failures. Approved, rejected, and changes-requested all complete normally and carry an outcome. Failure is reserved for genuine errors, so an agent can branch on a human's judgement without treating disagreement as a fault.

Works with or without the Tasks extension. Support varies across MCP clients, so every asynchronous tool has a synchronous fallback with identical semantics and identical IDs. Tasks is an upgrade in how a handle is delivered, never in what it means.

Development

Requires Node.js 20 or newer.

npm install
npm run verify     # boundary checks, lint, typecheck, tests
npm run build

Individual steps:

npm run check:deps      # dependency allowlist
npm run check:boundary  # copied-code fingerprints
npm run lint
npm run typecheck
npm test

The boundary checks

This repository is public; the SwipeFlow backend is not. The MCP server reaches SwipeFlow only through its public REST API — never a database, never a shared private module.

Two guards enforce that mechanically rather than by review discipline:

• check:deps — every dependency must be declared in allowed-dependencies.json. Adding one is a deliberate act. Stale entries also fail, so the allowlist cannot quietly accumulate grants.

• check:boundary — scans source for the fingerprints of backend code having been copied across: database drivers, backend-only credential surfaces, relative imports that escape the repository.

Both run in CI ahead of lint and tests, and both are themselves covered by tests in test/boundary.test.ts — a guard nobody exercises is a guard that silently stops working.

Contributing

Issues and discussion: https://github.com/swipeflow/swipeflow-mcp/issues

License

Apache 2.0