F
licenseNot graded
qualityC
maintenanceEnables AI agents to manage Jira and Confluence directly, including issue tracking, sprint management, and knowledge base operations through natural language.
-
Paperclip MCP server
by auralab-dev
This server is an MCP bridge that lets an agent read and manage Paperclip issues, comments, documents, agents, and runtime context through concise Markdown tools.
Read/wake context:
paperclip_contextandpaperclip_inboxexpose run/wake state and the current inbox without API calls.Issues: fetch one issue (
paperclip_issue), list/search issues (paperclip_issues), and read compact heartbeat context (paperclip_heartbeat_context).Issue lifecycle: create (
paperclip_issue_create), update (paperclip_issue_update), checkout/claim (paperclip_issue_checkout), and release (paperclip_issue_release).Comments: read threads (
paperclip_comments) and add comments (paperclip_comment_add).Documents: list (
paperclip_documents), read (paperclip_document), and create/update (paperclip_document_put) issue documents.Agents: list company agents or view one agent (
paperclip_agents).Raw API fallback: call relative Paperclip API paths not covered by dedicated tools (
paperclip_raw), with external URLs rejected.Large read results are automatically saved as immutable Markdown snapshots instead of being returned inline, controlled by token thresholds and an artifact directory.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Paperclip MCP server List open issues assigned to me and summarize the latest comments."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Paperclip MCP server
About
An MCP server for Paperclip. It wraps the Paperclip HTTP API in a small set of agent-oriented tools and communicates over stdio.
Related MCP server: docket
What does it do?
The server simplifies the Paperclip API for language models:
turns API responses into compact Markdown;
provides dedicated tools for common issue, comment, document, and agent work;
returns short acknowledgements for mutations instead of entire API responses;
keeps a guarded raw API tool for endpoints without a dedicated tool;
rejects external URLs in the raw tool.
Read responses are returned inline until they exceed
PAPERCLIP_MCP_INLINE_TOKEN_THRESHOLD. Larger responses are written as immutable
Markdown snapshots and the tool returns the file path instead. Snapshots are
read-only caches and may become stale; call the tool again when current state
matters.
Usage
Requires Node.js 22.19+ and pnpm 11.
pnpm install --frozen-lockfile
pnpm run build
PAPERCLIP_API_URL=http://localhost:3100 \
PAPERCLIP_API_KEY=your-key \
pnpm startExample MCP configuration:
{
"mcpServers": {
"paperclip": {
"command": "node",
"args": ["/absolute/path/to/paperclip-mcp/dist/index.js"]
}
}
}Tools
Tool | Description |
| Read the current run and wake context without an API call. |
| Read the current agent inbox. |
| Read one issue. |
| Read the compact heartbeat context for an issue. |
| List or search company issues, including user-touched, archived, and unread filters. |
| Create an issue or subtask. |
| Update issue fields, status, assignment, or comments. |
| Atomically claim an issue for the current agent. |
| Release a checked-out issue to |
| Read issue comments. |
| Read one issue comment. |
| Add a comment to an issue, optionally reopening it or interrupting its active run. |
| List, link, or unlink approvals on an issue. |
| List, read, or create company approvals. |
| Approve, reject, request revision for, or resubmit an approval. |
| Read or add approval review comments. |
| List, inspect, propose, decide, dismiss, or cancel Paperclip decisions. |
| Manage decision queues and their attention items. |
| Read or update decide-by and snooze state for attention items. |
| List, read, create, update, or delete Paperclip goals. |
| List, read, create, update, or delete Paperclip projects. |
| Manage project workspaces and runtime services. |
| List documents attached to an issue. |
| Read one issue document, optionally as raw base64 or a local path. |
| Read an issue document body as raw base64 or a local path. Defaults to base64. |
| Create or update an issue document. |
| Upload an image or other file attachment from a local path or base64 data. |
| List binary files attached to an issue. |
| Read an issue attachment as raw base64 or a local path. Defaults to base64. |
| Read a project or execution workspace file as raw base64 or a local path. Defaults to base64. |
| List company agents or read one agent. |
| Submit a governance-aware agent hire, with optional issue linkage and managed instructions. |
| Call a relative Paperclip API path not covered above. |
Environment variables
Name | Required | Default | Description |
| Yes | — | Paperclip base URL. |
| No | — | Bearer token for API requests. |
| No | — | Company context; required by company-scoped tools. |
| No | — | Current agent; required for issue checkout. |
| No | — | Run identity sent on mutations and used in snapshot paths. |
| No | — | Current task context. |
| No | — | Wake reason exposed by |
| No | — | Comment that triggered the run. |
| No | — | Current approval context. |
| No | — | Current approval status. |
| No | — | Comma-separated linked issue IDs. |
| No | — | JSON wake payload rendered by |
| No | OS temp directory | Snapshot output directory. |
| No |
| API request timeout. |
| No |
| Maximum estimated tokens returned inline. |
| No |
| Maximum binary size returned as base64. Use |
| No |
| Additional request headers as a JSON object. |
| No |
| Enable operation telemetry. |
| No | — | Optional telemetry JSONL output path. |
Custom headers
Use PAPERCLIP_MCP_HEADERS_JSON for reverse-proxy or routing headers:
export PAPERCLIP_MCP_HEADERS_JSON='{"CF-Access-Client-Id":"...","CF-Access-Client-Secret":"..."}'Header names and values are validated at startup. Values containing CR or LF
are rejected. PAPERCLIP_API_KEY overrides a custom Authorization header, and
PAPERCLIP_RUN_ID overrides X-Paperclip-Run-Id on mutations.
Development
pnpm install --frozen-lockfile
pnpm run check
pnpm run buildscripts/test.sh is an end-to-end test against a disposable Paperclip company.
Copy .env.example to the ignored .env.test, fill in its values, and explicitly
set PAPERCLIP_TEST_ALLOW_WRITES=1 before running it.
cp .env.example .env.test
scripts/test.shAvailable Tools
16 toolspaperclip_agentsRead Paperclip agentsARead-onlyIdempotent
List company agents, or fetch one agent when id is supplied. Returns Markdown inline below the configured token threshold and otherwise only a new immutable snapshot path. Use all_fields=true only when compact agent fields are insufficient.
Inputs: id, all_fields.
paperclip_comment_addAdd Paperclip commentA
Add a comment to authoritative Paperclip state. Returns only a compact acknowledgement; the full created comment response is not injected into context.
Inputs: body (required), issue_id (required), reopen.
paperclip_commentsRead Paperclip commentsARead-onlyIdempotent
Fetch issue comments as Markdown. Results are inline below the configured token threshold and otherwise returned as a new immutable snapshot path. Use after_comment_id for deltas instead of replaying an entire thread when possible. Call again for fresh comments.
Inputs: issue_id (required), limit, order, all_fields, +1 more.
paperclip_contextPaperclip runtime contextARead-onlyIdempotent
Read the current Paperclip run/wake environment without an API call. Returns LLM-friendly Markdown inline when it fits the configured token threshold; otherwise returns only a new immutable snapshot path.
Inputs: no named parameters.
paperclip_documentRead Paperclip issue documentARead-onlyIdempotent
Fetch one issue document as Markdown. Results are inline below the configured token threshold and otherwise returned as a new immutable snapshot path. Annotation loading is controlled explicitly with include_annotations/include_annotation_comments. all_fields=true only expands fields from the same response.
Inputs: key (required), issue_id (required), all_fields, include_annotations, +1 more.
paperclip_document_putCreate or update Paperclip issue documentADestructive
Create a document or append a new revision. Updating an existing document normally requires base_revision_id from a fresh paperclip_document result. Returns only a compact acknowledgement.
Inputs: key (required), body (required), issue_id (required), title, +2 more.
paperclip_documentsList Paperclip issue documentsARead-onlyIdempotent
List issue documents as compact Markdown. Results are inline below the configured token threshold and otherwise returned as a new immutable snapshot path. Default output omits document bodies; call paperclip_document for a body or all_fields=true for every returned field.
Inputs: issue_id (required), all_fields.
paperclip_heartbeat_contextRead Paperclip heartbeat contextARead-onlyIdempotent
Fetch GET /api/issues/:id/heartbeat-context explicitly. Returns Markdown inline when it fits the configured token threshold; otherwise returns only a NEW immutable snapshot path. Use this when the smaller wake/execution context is what you want. all_fields=true only expands fields from this same heartbeat-context response.
Inputs: id (required), all_fields.
paperclip_inboxPaperclip inboxARead-onlyIdempotent
Fetch the current agent compact inbox. Returns Markdown inline when it fits the configured token threshold; otherwise returns only a new immutable snapshot path. Call again whenever fresh assignment state matters.
Inputs: no named parameters.
paperclip_issueRead Paperclip issueARead-onlyIdempotent
Fetch one issue with GET /api/issues/:id. Returns Markdown inline when it fits the configured token threshold; otherwise returns only a NEW immutable snapshot path. all_fields=true only expands fields from that same response; it never changes the endpoint. Never edit snapshots to modify Paperclip.
Inputs: id (required), all_fields.
paperclip_issue_checkoutCheckout Paperclip issueADestructiveIdempotent
Atomically claim an issue for the current agent. A 409 is terminal: do not retry or steal the lock. Set reclaim_stale=true only when adopting your own stale in_progress checkout after a crashed run.
Inputs: id (required), reclaim_stale, expected_statuses.
paperclip_issue_createCreate Paperclip issueA
Create an issue/subtask in authoritative Paperclip state. Returns only a compact acknowledgement; the full created issue response is deliberately not injected into model context.
Inputs: title (required), extra, status, goal_id, +8 more.
paperclip_issue_releaseRelease Paperclip issueADestructive
Release the current agent checkout and return the issue to todo. Returns only a compact acknowledgement.
Inputs: id (required).
paperclip_issuesList or search Paperclip issuesARead-onlyIdempotent
Return a compact Markdown list from GET /api/companies/:companyId/issues. With no filters and no limit, Paperclip returns all visible company issues. Filters narrow the list; limit caps it. Results are inline below the configured token threshold and otherwise returned as a snapshot path. Use paperclip_issue for details on one issue.
Inputs: q, limit, status, label_id, +9 more.
paperclip_issue_updateUpdate Paperclip issueADestructive
Update authoritative issue state. Use this for status/assignment/field changes and optional comments; never edit snapshot files. Returns only a compact acknowledgement.
Inputs: id (required), extra, title, reopen, +13 more.
paperclip_rawRaw Paperclip API fallbackA
Fallback for Paperclip endpoints not covered by dedicated tools. Relative same-origin paths only. GET/HEAD return Markdown inline below the configured token threshold and otherwise only a new immutable snapshot path; mutations return only a compact acknowledgement. Prefer dedicated tools.
Inputs: path (required), body, query, method, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
A4/5.0
Scored across 16 tools
Disambiguation4/5
Most tools target a distinct resource and action, with clear singular/plural pairs such as issue/issues and document/documents. The main ambiguity is paperclip_context vs paperclip_heartbeat_context, but their descriptions differentiate current run/wake state from an issue-specific heartbeat.
Naming Consistency5/5
All tools share the paperclip_ prefix and follow a predictable pattern: read operations use resource nouns while mutations use resource_action naming like paperclip_issue_create and paperclip_comment_add. The paperclip_raw fallback is clearly labeled and does not disrupt the overall convention.
Tool Count4/5
At 16 tools the surface is slightly above the ideal 3-15 range, but the count is justified by the domain: issue lifecycle, comments, documents, agent lookup, context retrieval, and a raw fallback each have a distinct purpose. Nothing feels redundant or excessive.
Completeness4/5
The core issue workflow is well covered: list/get/create/update/checkout/release, plus comments, documents, agents, and context. Minor gaps such as no explicit delete or comment edit exist, but the update operations and paperclip_raw fallback give agents practical workarounds.
Maintenance
ActivityStale
ResponsivenessNo recent community issues
Related MCP Connectors
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Track issues, projects and dependencies with your agent in a workspace you control.
Task and sprint coordination for humans and AI agents, with scoped API keys and full audit trail.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables agents to create and update issues, post comments, and manage docs in a self-hosted issue tracker, with changes visible live in the web UI.23 npm2MIT
- FlicenseNot gradedqualityAmaintenanceEnables AI agents to retrieve Git-backed project context—kickoff cards, acceptance criteria, handoffs, progress, and next actions—and to append validated, audited progress events under scoped credentials.-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to search and read tickets and their conversations, contacts, companies, agents, groups, knowledge base articles, SLA policies, business hours and canned responses, and, on explicit request, create and update records, reply to tickets, add notes, and perform confirmed deletes, merges or conversions. It is stateless and multi-tenant, taking per-request credentials via HTTP headers so every action is performed as the designated agent.Apache 2.0