qodflow-mcp

@qodflow/mcp-server

Model Context Protocol (MCP) server for QodFlow. Lets AI agents like Claude Desktop, Cursor, and ChatGPT Desktop drive a QodFlow workspace through a Personal Access Token.

Install

cd mcp-server
npm install
npm run build

The binary is exposed as qodflow-mcp.

Configure your agent

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)

{
  "mcpServers": {
    "qodflow": {
      "command": "node",
      "args": ["/absolute/path/to/qodflow/mcp-server/dist/index.js"],
      "env": {
        "QODFLOW_API_TOKEN": "qf_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cursor / ChatGPT Desktop

Use the same command + env shape; consult your client's docs for the exact config path.

Get a token

1. Sign in to QodFlow.
2. Go to Settings → API Keys.
3. Click New token, give it a name, pick the minimum scopes you need (jobs:read + stages:read is enough for the current toolset), and copy the plaintext once — it isn't shown again.
4. Paste it as QODFLOW_API_TOKEN in your agent config.

For integration testing, toggle Test mode at token creation; the prefix becomes qf_test_ and the token binds to test-mode Stripe products.

Tools (v0.1)

Tool	Scope required	Plan	Description
list_jobs	jobs:read	any	Most recent jobs, paginated.
list_stages	stages:read	any	Pipeline stages with order, color, SLA.
list_tags	tags:read	any	Tags defined on the workspace.
list_members	members:read	any	Team members (id, name, masked email hint, role).
create_job	jobs:write	any*	Create a job in the first (or given) stage.
update_job	jobs:write	any*	Update title, description, priority, PO number.
move_job	jobs:write	any	Move a job to another stage.
assign_job	mcp:assign	DIAMOND	Assign a job to a member (or null to unassign).
create_tag	tags:write	PREMIUM+	Create a tag.
update_stage	stages:write	any*	Rename a stage, change SLA/color.
claim_job / release_job	mcp:claim	any	Atomically claim/release a job (lease-based).
report_progress	mcp:claim	any	Append a progress note to a job's timeline.
request_human_decision	mcp:decide	any	Ask a human to pick between options.
resolve_decision	mcp:resolve	any	Resolve an open decision.
attach_evidence	mcp:evidence	any	Attach a note (+ optional URL) as evidence.
get_timeline / list_decisions / list_evidence	jobs:read	any	Read a job's timeline / decisions / evidence.

* Subject to plan limits (active-job cap, priority/tags gating). When a call exceeds a plan gate or quota the tool returns an error whose text includes an Upgrade: <url> hint you can relay to the user.

Destructive verbs (delete_team, mass move, etc.) are never exposed via MCP. They live behind the UI confirm-literal guard only.

Security model

• Token scopes are enforced server-side on every call — this binary cannot grant itself privileges it wasn't issued.
• Audit log is written for every token-authed request and is visible to team owners.
• Killswitch: revoke the token from Settings → API Keys to stop the agent immediately.
• Rate limit: 120 requests/minute per token (server-enforced).
• This binary does not persist anything to disk and does not phone home — it only talks to QODFLOW_API_BASE (default https://www.qodflow.com).

Token handling on shared workstations

The MCP host (Claude Desktop, Cursor) launches this binary as a child process and passes the token via the QODFLOW_API_TOKEN environment variable. On Linux that environment is readable by any other process running as the same user via /proc/PID/environ, and similar exposure exists on macOS via ps -ewww in some configurations. If you operate on a shared workstation or a machine where other untrusted code runs (CI runners, contractor laptops, etc.):

1. Prefer a per-user token over a shared one — issue narrow scopes and rotate every 90 days.
2. Use the OS keychain for storage: security add-generic-password (macOS), secret-tool (GNOME), wincred (Windows). Have your host config read from it at launch rather than embedding the literal token.
3. Future: v1.1 will accept the token via stdin write at startup instead of env, eliminating /proc/PID/environ exposure. Track issue [token-via-stdin] for adoption.
4. Never commit claude_desktop_config.json or equivalent to a repository. It contains your token.

Environment variables

Var	Required	Default	Description
QODFLOW_API_TOKEN	yes	—	qf_live_… or qf_test_… PAT.
QODFLOW_API_BASE	no	https://www.qodflow.com	Override for self-hosted or local dev. Must be the www host — the apex redirects and Node strips the auth header on the cross-origin hop.

Development

npm run dev   # tsx watch on src/index.ts

Roadmap: write tools (create job, move job), then audit-log read, then v1.1 hosted-HTTP transport with OAuth.