@bespoke-tech/paragon-mcp

MCP (Model Context Protocol) server for PARAGON — manage your projects, tickets, docs, and agent tasks from any MCP-capable AI client: Claude Code, Claude Desktop, Cursor, and friends.

Quick start

1. Create an API key — in PARAGON: Settings → API Keys. Keys are prefixed paragon_, impersonate their owning user (all your permissions, enforced server-side), and can be flagged read-only.
2. Register the server with your client:

{
  "mcpServers": {
    "paragon": {
      "command": "npx",
      "args": ["-y", "@bespoke-tech/paragon-mcp"],
      "env": { "PARAGON_API_KEY": "paragon_…" }
    }
  }
}

Claude Code CLI equivalent:

claude mcp add paragon -e PARAGON_API_KEY=paragon_…

Configuration

| Env var | Required | Default | Purpose | |---|---|---|---| | PARAGON_API_KEY | yes | — | Your PARAGON API key (paragon_…) | | PARAGON_API_URL | no | https://paragon.mybts.io/api/v1 | Upstream API base (for self-hosted PARAGON) |

Transport is stdio. Requires Node ≥ 18.

Tools

Tools span projects & workflow transitions, tickets / tasks / links / attachments (incl. project-wide ticket listing/filtering and ticket/comment deletion), documentation pages (incl. page revisions and search), organizations & teams, agent tasks & transcripts (incl. user-facing restart), labels, and AI workflow triggers. Your client's tool list shows everything with descriptions. The complete tool reference is below, regenerated from source with each release.

75 tools

Agent Tasks & Prompts (6)

| Tool | Description | |------|-------------| | list_agent_tasks | List all agent tasks with optional filtering by status and agent type | | get_agent_task | Get a specific agent task by ID with full details including ticket context | | get_agent_task_messages | Read the transcript of an agent task (read-only): returns the messages the agent produced while running, ordered by createdAt ascending — i.e. the order they were recorded. Each row carries messageId, role, content (string or null for tool-only/partial rows), and parts (the raw structured message parts), so transcripts can be VERY LARGE for long runs; they are returned verbatim with no truncation — fetch only when the full history is actually needed. Requires project access to the task's ticket: a missing task returns 404 ('Agent task not found') and no project access returns 403. This tool is read-only by design; writing messages back is the plugin export path and is not exposed here. | | transition_agent_task | Transition an agent task to a terminal state: complete (running→completed) or fail (running→failed). Tasks transition from pending→running automatically when PARAGON dispatches the prompt to OpenCode. | | retry_agent_task | Restart (re-dispatch) a failed, blocked, or cancelled agent task: the old row is cancelled, the ticket's work state resets to ready, and the ticket re-enters the standard dispatch flow, creating a replacement task. Only failed, blocked, or cancelled tasks can be restarted (running/queued/pending/completed are rejected). Requires project WRITE access via your API key — read-only keys are rejected with 403. The replacement agent session starts asynchronously AFTER the call returns and may take a minute to appear; if the organization is over its agent-run quota, the replacement task is created as queued and dispatches automatically once quota allows. | | agent_prompt | Get, update, or delete a custom agent prompt for a project. Use action 'get' to retrieve prompts, 'update' to set custom prompts, or 'delete' to revert to default. The custom prompt is always treated as ADDITIONS: it is appended after PARAGON's core instructions for that agent, which remain fully in force (conflicts resolve to the core instructions). |

Labels (6)

| Tool | Description | |------|-------------| | list_labels | List all labels for a PARAGON project (project slug required). Labels are also embedded in get_project, but this tool is cleaner for label-only operations. | | create_label | Create a new label for a PARAGON project. Requires project admin access. Name must be non-empty; color (optional) must be a 6-digit hex like #6b7280 (defaults to #6b7280 when omitted). | | update_label | Update a label's name and/or color by label ID. Requires project admin access. At least one of name or color must be provided. | | delete_label | Delete a label by ID. Requires project admin access. Cascades to remove all ticket-label associations. | | add_label_to_ticket | Attach a label to a ticket. Idempotent (re-attaching is a no-op). The ticket id accepts a UUID or PREFIX-NUMBER (e.g. 'BP-213'); the label id must be a UUID. Requires write access to the ticket's project and the label must belong to the same project. Emits a label_added activity on a real attach. | | remove_label_from_ticket | Detach a label from a ticket. Idempotent (detaching a not-attached label is a no-op). The ticket id accepts a UUID or PREFIX-NUMBER (e.g. 'BP-213'); the label id must be a UUID. Requires write access to the ticket's project and the label must belong to the same project. Emits a label_removed activity on a real detach. |

Organizations & Teams (11)

| Tool | Description | |------|-------------| | list_organizations | List all PARAGON organizations the authenticated user is a member of | | get_organization | Get a PARAGON organization by slug. Use includeMembers/includeTeams to include those (off by default to reduce output). | | create_organization | Create a new PARAGON organization. The name is slugified into the org's URL identifier — names that slugify to a reserved URL segment (e.g. "settings", "admin", "api") or to an empty slug are rejected with a 400 (BP-506); choose a different name. | | update_organization | Update a PARAGON organization's details | | delete_organization | Delete a PARAGON organization (only owners can delete) | | get_organization_github_config | Get GitHub configuration for an organization (githubOrg, commitEmail, commitName). Note: The Personal Access Token (PAT) is NOT exposed via MCP for security reasons — the organization object only reports a githubPatConfigured boolean. | | list_teams | List all teams for a PARAGON organization | | get_team | Get a PARAGON team by ID with members, organization, and projects | | create_team | Create a new team in a PARAGON organization (requires org owner/admin role). organizationId must be a valid UUID (use list_organizations to get IDs) — non-UUID values are rejected client-side with a validation error. The caller must be an owner/admin of that organization (403 otherwise). | | update_team | Update a PARAGON team's details | | delete_team | Delete a PARAGON team (requires org owner/admin role) |

Documentation / Pages (16)

| Tool | Description | |------|-------------| | list_pages | List all pages for a PARAGON project (standalone docs, research, planning, whiteboards) | | search_pages | Fuzzy-search project documentation pages by title and content (pg_trgm). Returns ranked results with content snippets. Use this when you need to find docs by topic and don't already have a page ID. | | get_page | Get a specific page by ID | | list_page_revisions | List a page's revision history, newest first. Consecutive same-author autosave revisions within ~5 minutes are coalesced into a single entry (manual/agent/restore edits are never coalesced; coalesced entries carry a coalescedCount). limit is clamped server-side to 1-200 (default 50). A 404 means the page is missing OR you lack access — the two are indistinguishable by design (no existence leak). | | get_page_revision | Get a single page revision by ID — the full snapshot (content + title, plus the whiteboard scene when the page is a whiteboard) for diffing or restore previews. A 404 means the page or revision is missing OR you lack access to the page — indistinguishable by design (no existence leak). | | restore_page_revision | Restore a page to a prior revision's content and title (plus the whiteboard scene when the revision has one). Append-only: this creates a NEW restore-tagged revision at the top of the history — the original revision row is never mutated or deleted, so history stays intact. Restoring an identical state is a no-op (no new revision). Requires a writable API key with project write access. A 404 means the page or revision is missing OR you lack access (no existence leak); a 403 means the key is read-only or lacks project write access. | | create_page | Create a new standalone documentation page or whiteboard. For whiteboards, pass whiteboardData with the Excalidraw scene. | | update_page | Update a page's title, content, parent, or whiteboard scene. Pass parentId to nest the page under another page (BP-337 sub-pages), or null to move it back to the project root. Pass whiteboardData (Excalidraw scene) to write the board. | | delete_page | Delete a page (and all its child pages) | | ticket_research | Get or update the research page for a ticket. Use action 'get' to retrieve the research page, or 'update' to create/update it. | | ticket_planning | Get or update the planning page for a ticket. Use action 'get' to retrieve the planning page, or 'update' to create/update it. | | list_page_attachments | List all file attachments for a documentation page | | delete_page_attachment | Delete a file attachment from a documentation page | | list_page_links | List all typed page-to-page links (relates_to, depends_on, supersedes) for a documentation page, both outgoing and incoming. Pages must belong to the same project. | | link_page | Create a typed link between two documentation pages. Source and target pages must belong to the same project, and you cannot link a page to itself. 'relates_to' is symmetric and deduped in both directions. | | unlink_page | Remove a typed link between two documentation pages. |

Projects (9)

| Tool | Description | |------|-------------| | list_projects | List PARAGON projects with optional filters. By default returns ALL projects the caller is authorized to see (no cap). Filters (all optional, AND-combined when multiple are provided): - organizationSlug / organizationId: scope to a specific organization - userId: scope to projects where the user is a member, lead, or creator - membershipRole: sub-filter for userId (admin, member, viewer, any — default: any) - sort: field to sort by (createdAt, name, updatedAt — default: createdAt) - order: sort direction (asc, desc — default: desc) - includeArchived: include archived projects (currently a no-op stub) Authorization rules: - Super-admin and agent roles: can list across all organizations and use any filter - Regular users: can only filter by organizations they belong to, and userId must be their own ID - Cross-tenant queries from non-privileged users return 403 Use limit only when you genuinely need pagination. Response includes a total count. | | get_project | Get a PARAGON project by slug. The response ALWAYS embeds the project's tickets (slim data: id, number, title, status, priority, workState, assigneeId, timestamps — there is no flag to turn this off; the output can be large for active projects). Use get_ticket or get_tickets_batch for full ticket details. | | create_project | Create a new PARAGON project in an existing organization. Required: organizationId (UUID) — the organization to create the project in (use list_organizations to find IDs). The caller must be a member of that organization, otherwise 403. Uniqueness is GLOBAL (not scoped to your organization): - prefix (explicit or auto-generated from the name) must not be used by ANY existing project — a collision returns 409 - the slug derived from the name must not be used by ANY existing project — a collision returns 409; choose a different name Optional teamId (UUID) must belong to organizationId, otherwise 400. Optional repoUrl must be an http(s) URL, otherwise 400. On success the caller becomes the project's lead and admin member, and default AI workflow triggers are installed. | | update_project | Update a PARAGON project's details. QA test credentials are sensitive fields for automated testing. | | add_project_member | Add a user as a member to a PARAGON project | | remove_project_member | Remove a user from a PARAGON project | | list_transitions | List the configured workflow transitions for a PARAGON project. Each transition is a permitted fromStatus -> toStatus ticket status move. Use this to inspect the workflow graph that gates ticket status changes (the graph is only enforced when the project's workflowRestricted flag is true). | | set_transitions | Bulk-replace the set of permitted workflow transitions for a PARAGON project. This is a destructive full-replace: the entire transition set is overwritten (delete-all + insert). Every fromStatus/toStatus must be a valid TicketStatus AND a member of the project's enabledStatuses; the server validates this before writing so a malformed request cannot wipe the existing set. Requires project admin access. Use list_transitions first to see the current set, then send the complete desired set. | | delete_transition | Surgically remove a single workflow transition from a PARAGON project, either by its id or by a fromStatus+toStatus pair. Returns the deleted transition(s) as JSON. Use list_transitions to discover the id or the from/to values. Exactly one selector must be provided: either id, or both fromStatus and toStatus. Requires project admin access. |

Tickets, Tasks, Links & Attachments (20)

| Tool | Description | |------|-------------| | list_users | List PARAGON users (useful for getting user IDs for ticket assignment) | | create_ticket | Create a new ticket in a PARAGON project | | get_ticket | Get a PARAGON ticket by ID, including comments | | get_tickets_batch | Fetch multiple tickets at once by their IDs (max 15 tickets). Returns full ticket details including description and assignee info. | | list_tickets | List/filter tickets in a PARAGON project with server-side filtering, sorting, and pagination. Unlike get_tickets_batch (IDs only, max 15), this sweeps a whole project. Filters (all optional; any-of lists — a ticket matches if it hits ANY of the given values): - status: canonical statuses, including 'parked' (e.g. ['review', 'dev']) - assigneeId: user IDs (use list_users) and/or the sentinel 'unassigned' for tickets with no assignee — mixing both matches unassigned tickets AND the named assignees - priority / type / workState: any-of enums - updatedSince: ISO timestamp — inclusive >= on updatedAt (cheap delta sweep; NOT exactly-once sync) Pagination & shape: - limit (default 50, max 500) + offset; the response includes total = rows matching the filters IGNORING limit/offset, so you can detect truncation and page through - sort: updatedAt (default) | createdAt | priority | number; order: asc | desc (default desc). priority sorts by enum declaration order (asc = low → urgent) - includeDescription: true adds each ticket's description (bigger payload — off by default; rows are otherwise slim) Authorization rules: - API keys see only what their owning user sees; org-scoped keys are restricted to their org - Requires project access: unknown project slug → 404, no project access → 403 | | update_ticket | Update a PARAGON ticket | | delete_ticket | Permanently delete a ticket — IRREVERSIBLE. Cascades server-side: active agent tasks are cancelled, the ticket's git branch is best-effort deleted, attachments are removed from UploadThing, and a ticket_deleted activity entry is logged. Accepts a ticket UUID or a 'BP-19'-style display id. Preview first with get_ticket to confirm you have the right ticket before deleting. Authorization is enforced server-side: requires a writable API key whose user is a PROJECT ADMIN of the ticket's project — a 403 ('Forbidden: project admin access required') means the key's user is not a project admin and is correct behavior, not a bug. Returns {deleted, cleanup} where cleanup lists the side-effects performed. | | set_ticket_parent | Set or clear a PARAGON ticket's parent (BP-489 parent-child containment — e.g. hanging child tickets under an initiative). PURELY NAVIGATIONAL: containment never moves status in either direction (no auto-rollup, no inheritance). Pass parentTicketId=null to detach the ticket from its parent. Enforced server-side: the caller must have write access to the ticket's project and read access to the parent's project; the parent must exist, cannot be the ticket itself, must belong to the same organization (cross-project within the org is allowed), and must not create a containment cycle. An unknown or inaccessible parent 404s as "Parent ticket not found"; other violations 400 — always without writing. Both tickets get a paired ticket_parent_set / ticket_parent_cleared activity entry. | | add_comment | Add a comment to a PARAGON ticket | | delete_comment | Permanently delete a comment from a PARAGON ticket — IRREVERSIBLE. The comment must belong to the given ticket: a comment that exists under a different ticket (or an unknown comment/ticket) 404s rather than being deleted through the wrong path. Attachment cleanup (UploadThing) and the comment_deleted activity log entry are performed server-side, identical to the UI flow. Authorization is enforced server-side: requires a writable API key, and the key's user must be the comment's AUTHOR or a GLOBAL ADMIN — agent keys can typically only delete comments they authored themselves, so a 403 ('You can only delete your own comments') when targeting someone else's comment is correct behavior, not a bug. | | list_tasks | List all tasks (sub-items) for a PARAGON ticket | | create_task | Create a new task (sub-item) on a PARAGON ticket | | update_task | Update a task on a PARAGON ticket | | delete_task | Delete a task from a PARAGON ticket | | list_links | List all linked tickets for a PARAGON ticket (blocks, blocked by, related) | | create_link | Create a link between two PARAGON tickets (blocks or relates_to) | | delete_link | Remove a link between PARAGON tickets | | list_attachments | List all file attachments for a PARAGON ticket | | delete_attachment | Delete a file attachment from a PARAGON ticket | | get_attachment_content | Get the content of a file attachment. For text files (code, markdown, JSON, etc.), returns the file content. For binary files (images, PDFs), returns the download URL. |

AI Workflow Triggers (4)

| Tool | Description | |------|-------------| | list_triggers | List AI workflow triggers for a project. Each trigger maps ticket types/statuses/priorities to an AI workflow agent (its explicit agentType). Returns full trigger objects as JSON. | | create_trigger | Create a new AI workflow trigger for a project. Requires project admin access. agentType (required) is the agent this trigger dispatches — one of research/planning/dev/qa/merge/archivist. plan-review is not trigger-dispatched. Returns the created trigger object as JSON. | | update_trigger | Update an existing AI workflow trigger. Requires project admin access. Provide only the fields to change. agentType (optional) changes the dispatching agent — one of research/planning/dev/qa/merge/archivist; omitted leaves it unchanged. Returns the updated trigger object as JSON. | | delete_trigger | Delete an AI workflow trigger. Requires project admin access. Returns a success confirmation. |

Workflow Sequences (3)

| Tool | Description | |------|-------------| | list_workflow_sequences | List a PARAGON project's per-ticket-type workflow sequences — the ordered status chains (fromStatus → toStatus edges) that decide the next status when an AI agent finishes successfully. Returns one entry per ticket type in canonical order; a type with an empty steps array is close-only (its agent finishes transition nothing). The platform seed gives spike the lane backlog → research → archivist → done and initiative backlog → research → archivist → review (plus an inert review → done edge); the other types run backlog → research → planning, dev → qa → review → done (the merge agent finishes review), with a deliberate gap at planning (planning is close-only; the planning→dev move happens via plan approval). | | replace_workflow_sequence | Bulk-replace ONE ticket type's workflow sequence (delete its existing edges + install the new set — destructive for that type only). Requires project admin access. Rules enforced server-side BEFORE any write: every status must be a valid TicketStatus, and a fromStatus may appear at most once (the sequence is a linear chain — exactly one successor per status). Chain gaps are legal (a status with no edge has no successor — its agent finishes transition nothing) and an empty steps array is legal (close-only by configuration). Use list_workflow_sequences first, then send the complete desired edge set for the type. | | reset_workflow_sequence | Reset ONE ticket type's workflow sequence to the platform defaults: deletes the type's configured edges and re-seeds the default sequence for that type (spike: backlog → research → archivist → done; initiative: backlog → research → archivist → review with an inert review → done edge; other types: backlog → research → planning, dev → qa → review → done (the merge agent dispatches inside review behind merge approval and its finish advances review → done)). Requires project admin access. Use this to undo a replace_workflow_sequence without hand-reconstructing the default edges. |

Behavior notes

• Invalid ticket-status transitions return the error plus the valid target statuses.
• status and workState cannot be set in one call — set status first, then workState.
• List tools accept a limit; get_organization defaults to a lean response with opt-in includes (includeMembers/includeTeams); get_project always embeds slim tickets.

License

MIT