qodflow-mcp

Model Context Protocol (MCP) server for QodFlow, a kanban board with SLA tracking that people and AI agents share. Lets Claude Code, Claude Desktop, Cursor and other MCP clients create, move, assign and report on jobs through a scoped, revocable Personal Access Token.

Install

# Claude Code
claude mcp add qodflow -- npx qodflow-mcp
export QODFLOW_API_TOKEN=qf_live_…

Any other MCP client: run npx qodflow-mcp as the server command with QODFLOW_API_TOKEN in its environment (see below). Full guide: https://www.qodflow.com/docs/mcp

To build from source instead, run npm install then npm run build inside mcp-server/; the binary is qodflow-mcp.

Related MCP server: PilotDeck

Configure your agent

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

{
  "mcpServers": {
    "qodflow": {
      "command": "npx",
      "args": ["qodflow-mcp"],
      "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 (27)

* Subject to plan limits (active-job cap, 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.

Agent briefing

The server tells MCP clients to call get_briefing first in every session, and also attaches the briefing once, as an extra first text block starting with --- QodFlow briefing ---, to the first successful tool result of a session. If the briefing cannot be fetched within 2 seconds it is skipped silently and the tool result is returned as usual. It only needs jobs:read. Acknowledge each resolved decision you have read with ack_decision so it stops repeating.

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

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.