propath-mcp

MCP (Model Context Protocol) server for Propath (Productivity Pathways). Lets Claude Desktop / Claude Code read, create, update, and move tasks in a Propath workspace — built for AI-driven QA workflows.

It is a thin stdio adapter over Propath's Integration API v1 (/api/v1/*, see packages/backend/convex/apiRouter.ts). All authentication, tenant isolation, scopes, and board permissions are enforced by the Propath backend; this server just translates MCP tool calls into REST requests.

Tools

| Tool | Propath endpoint | Scope required | | --- | --- | --- | | list_boards | GET /api/v1/boards | boards:read | | list_columns | GET /api/v1/boards/{id}/columns | boards:read | | list_tasks | GET /api/v1/tasks | tasks:read | | get_task | GET /api/v1/tasks/{id} | tasks:read | | create_task | POST /api/v1/tasks | tasks:write | | update_task | PATCH /api/v1/tasks/{id} | tasks:write | | move_task | POST /api/v1/tasks/{id}/move | tasks:write | | list_comments | GET /api/v1/tasks/{id}/comments | tasks:read | | add_comment | POST /api/v1/tasks/{id}/comments | comments:write | | list_attachments | GET /api/v1/tasks/{id}/attachments | attachments:read | | get_attachment | GET /api/v1/attachments/{id}/content | attachments:read | | list_checklists | GET /api/v1/tasks/{id}/checklists | tasks:read | | list_custom_fields | GET /api/v1/tasks/{id}/custom-fields | tasks:read |

Typical QA flow the model chains on its own: list_boards → list_columns → create_task (in the open column) → later move_task (to inProgress / done) and add_comment.

A task's status is its column (open | inProgress | done | blocked | archived). Changing status = move_task, not update_task.

People are resolved for you

Tasks carry assignees: [{userId, name}] and comments carry author / mentions in the same shape — there is no need to call list_members and join by id. Email addresses appear in those objects only when the key also holds members:read.

Attachments are opt-in

Both attachment tools need the separate attachments:read scope, which is not part of the default set: they are the only way file contents leave the workspace. A workspace owner must tick it deliberately. Without it the other tools work exactly as before, and these two return 403.

Read contents with get_attachment, not downloadUrl. list_attachments still exposes a signed storage URL, but it points at Cloudflare R2, expires in ~15 minutes, and assumes the client can reach that host — which is a bad bet inside an agent loop or on a restricted network. get_attachment streams the bytes through the Propath deployment itself: no expiry, no CDN hop, same key and same scope. Files over 10 MB are refused with 413 and a downloadUrl to fall back to.

Reading a whole comment thread

list_comments returns at most 100 rows per call and defaults to newest-first. Pass order: "asc" to read chronologically, and keep paging while hasMore is true — a short first page does not mean the thread is short.

Configuration

| Variable | Value | | --- | --- | | PROPATH_API_KEY | Required. Integration key (pp_live_…) minted in Propath → Settings → Integrations | | PROPATH_API_URL | Optional override of the deployment origin. The production URL is baked into the package (DEFAULT_API_URL in src/propath.ts); set this only for staging or self-hosted deployments |

The key should carry at least: boards:read, tasks:read, tasks:write, comments:write (all part of the default scope set). Add members:read for email addresses and attachments:read for file downloads — neither is required for the core flow.

Development

npm install
npm run build          # tsc → dist/

# Interactive testing without Claude:
PROPATH_API_URL=https://your-deployment.convex.site \
PROPATH_API_KEY=pp_live_xxx \
npm run inspect        # opens MCP Inspector

Client setup (Claude Desktop)

Edit the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Once published to npm:

{
  "mcpServers": {
    "propath": {
      "command": "npx",
      "args": ["-y", "propath-mcp"],
      "env": {
        "PROPATH_API_KEY": "pp_live_…"
      }
    }
  }
}

Windows: if the tools don't appear, older Claude Desktop builds can't spawn npx directly — use "command": "cmd", "args": ["/c", "npx", "-y", "propath-mcp"].

Before publishing (local build), point at the compiled entry instead:

{
  "mcpServers": {
    "propath": {
      "command": "node",
      "args": ["/absolute/path/to/services/propath-mcp-server/dist/index.js"],
      "env": {
        "PROPATH_API_KEY": "pp_live_…"
      }
    }
  }
}

Restart Claude Desktop; the propath tools appear in the tools menu.

For Claude Code:

claude mcp add propath \
  -e PROPATH_API_KEY=pp_live_xxx \
  -- npx -y propath-mcp

An Arabic end-client guide ships with the package: README.ar.md.

Troubleshooting

MCP error -32000: Connection closed — the process died before the handshake. It is almost never the config: the usual cause is a version in args that isn't on npm (npx fails to resolve it and exits). Check with npm view propath-mcp version, then either pin an existing version or drop the @x.y.z suffix.

A missing or malformed PROPATH_API_KEY no longer kills the server — it starts, and every tool call answers with what to fix. That failure used to be indistinguishable from the one above.

To see what a client sees, drive the server by hand:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  | npx -y propath-mcp

The serverInfo.version in the reply is the build actually running — the way to confirm an upgrade took effect.

Security notes

• The API key is tenant-scoped: it can never see or touch another workspace.
• Per-key scopes narrow what the tools may do; the backend returns 403 (surfaced to the model verbatim) for anything outside them.
• Every request is audit-logged by the backend (apiRequestLogs), visible in Propath → Settings → Integrations.
• Keys can be revoked instantly from the same settings page.