Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/bruhsb/paperclip-mcp/llms.txt

Use this file to discover all available pages before exploring further.

Labels in Paperclip are company-wide taxonomy entries — each label has a name, an optional hex color, and a UUID. They can be attached to issues via the labelIds field when creating or updating an issue, making them the primary mechanism for categorizing work. The two label tools cover the full lifecycle: list existing labels to build a name-to-UUID cache, and create new labels when a required taxonomy entry is missing.

List Labels

Retrieve all labels defined for the current company

Create Label

Create a new label with a name and optional hex color
Labels are scoped to the company set by PAPERCLIP_COMPANY_ID. To apply a label to an issue, pass the label UUID in the labelIds array when calling paperclip_create_issue or paperclip_update_issue.

​
paperclip_list_labels

List all labels defined for the current company, returning a paginated envelope.
​
limit
integer
Maximum labels per page. Range 1–100. Defaults to 50.
​
offset
integer
Number of labels to skip for pagination. Defaults to 0.
​
response_format
"markdown" | "json"
Output format. markdown (default) produces a human-readable list; json returns a structured envelope.
Returns: Pagination envelope { items: Label[], total, count, offset, limit, has_more, next_offset }. Each Label item contains: id, name, color (hex string), createdAt. Usage notes:
  • Call this tool at the start of a run to build a local name → UUID cache for labels you plan to reference.
  • If you already have the label UUID, pass it directly to the issue tools — no need to list again.
  • Use limit and offset to page through companies with large label taxonomies.
Errors:
CodeMeaningResolution
401Authentication failedCheck PAPERCLIP_API_KEY
403Permission deniedVerify PAPERCLIP_COMPANY_ID is correct
{
  "tool": "paperclip_list_labels",
  "arguments": {
    "limit": 100,
    "response_format": "json"
  }
}

​
paperclip_create_label

Create a new label for the current company. Labels must have unique names within a company — check for existence with paperclip_list_labels before creating.
​
name
string
required
Label name. Typically namespaced for clarity (e.g. source:agent, type:bug, priority:high). Must be non-empty.
​
color
string
A 6-digit hex color string including the # prefix (e.g. #6366f1). Omit to use the server default color.
Returns: The created label object: id, name, color, createdAt.
Use a namespaced naming convention like source:agent or type:bug to keep your label taxonomy organized and unambiguous as it grows.
Usage notes:
  • Use this during a “Label Bootstrap” step to seed missing taxonomy labels before processing issues.
  • Always check paperclip_list_labels first — creating a duplicate name will return a 409 conflict.
  • The color value must be exactly 6 hex digits with a leading #; values like #fff or red will fail validation.
Errors:
CodeMeaningResolution
400Validation failureCheck name is non-empty; color must be valid 6-digit hex
401Authentication failedCheck PAPERCLIP_API_KEY
409Label name already existsFetch the existing UUID from paperclip_list_labels
{
  "tool": "paperclip_create_label",
  "arguments": {
    "name": "source:agent",
    "color": "#6366f1"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us