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.

Every request the MCP server makes to the Paperclip control plane is authenticated with a Bearer token read from the PAPERCLIP_API_KEY environment variable. There are exactly two key types — agent keys and board keys — and the single most common cause of unexpected 403 errors is calling a board-only tool while holding an agent key. This guide explains the distinction, lists every board-only tool by domain, and covers how auth is wired in production heartbeat runs versus local development.

​
Two key types

Agent Key

Created via paperclip_create_agent_key or the Paperclip dashboard agent settings. Issued to autonomous agents such as Engineer, QA, and Scrum Master. Covers all read operations and the vast majority of write operations — issues, comments, documents, goals, projects, labels, routines, and attachments.

Board Key

Generated by a human user from Paperclip account settings. Held by human operators or board-level agents (e.g. CEO). Superset of agent-key permissions, plus destructive operations and approval decisions. Required for any action that enforces separation of duties.
Key typeHow to obtainTypical bearerScope
Agent keypaperclip_create_agent_key or dashboard agent settingsAutonomous agents (Engineer, QA, etc.)Read and write most issue, comment, document, goal, and project operations
Board keyGenerated by a human from Paperclip account settingsHuman operators or board-level agents (CEO)Everything an agent key can do, plus destructive operations and approval decisions

​
How auth is wired

In production, Paperclip injects PAPERCLIP_API_KEY, PAPERCLIP_AGENT_ID, PAPERCLIP_COMPANY_ID, and PAPERCLIP_RUN_ID automatically before each heartbeat run. You never set these manually — the platform provisions the correct key type for the agent’s configured role.
# These are injected by the Paperclip runtime — do not hardcode them.
PAPERCLIP_API_KEY=pclp_agent_...
PAPERCLIP_API_URL=https://your-instance.paperclip.ai
PAPERCLIP_AGENT_ID=4af69525-85d4-451d-a138-70f82287e578
PAPERCLIP_COMPANY_ID=org-uuid
PAPERCLIP_RUN_ID=902e27b0-c67c-4030-b666-9bbd658bf019

​
Decision tree — which key do you need?

What are you trying to do?
│
├── Read issues, comments, documents, goals, projects, labels,
│   agents, routines, approvals, activity, attachments?
│   └── Agent key is sufficient.
│
├── Create or update issues, comments, labels, goals, projects,
│   documents, routines, or agents?
│   └── Agent key is sufficient.
│
├── Checkout or release an issue?
│   └── Agent key is sufficient.
│
├── Delete a document (paperclip_delete_document)?
│   └── Board key required. The tool description begins with
│       "⚠ Board-only:" and the Paperclip API returns 403 with an agent key.
│
├── Approve or reject an approval (paperclip_approve,
│   paperclip_reject, paperclip_request_revision)?
│   └── Board key required (403 with agent key).
│
├── Clear a stale checkout lock via paperclip_update_issue
│   (passing executionRunId: null)?
│   └── Board key required.
│
└── Manage agent configuration, permissions, or keys
    (paperclip_update_agent, paperclip_update_agent_permissions,
    paperclip_create_agent_key, paperclip_terminate_agent,
    paperclip_pause_agent, paperclip_resume_agent, etc.)?
    └── Board key required for cross-agent mutations.
        An agent can read its own config with an agent key.

​
Board-only tools

The following tools return 403 Forbidden when called with an agent key. Use a board-scope key, or have a human operator perform these actions.
Tools that begin with ⚠ Board-only: in their description are enforced at the HTTP API level — even if the MCP tool schema does not reject the call, the Paperclip server will return 403. Switching key types is the only fix.

​
Documents

ToolWhy board-only
paperclip_delete_documentDocument deletion is irreversible — restricted to prevent agents from discarding audit-relevant records.

​
Approvals

ToolWhy board-only
paperclip_approveFinal approval decision requires human/board authority.
paperclip_rejectRejection enforces separation of duties — the submitter cannot reject their own request.
paperclip_request_revisionRequesting a revision is part of the approval decision flow.
Creating an approval (paperclip_create_approval, paperclip_create_agent_hire) and commenting on one (paperclip_add_approval_comment) are both permitted with an agent key. Only the final decision verbs require board scope.

​
Agent management (cross-agent mutations)

ToolWhy board-only
paperclip_update_agentMutating another agent’s config.
paperclip_update_agent_permissionsSetting canAssignTasks, canCreateAgents.
paperclip_create_agent_keyIssuing new authentication keys.
paperclip_terminate_agentPermanent agent termination.
paperclip_pause_agentLifecycle control.
paperclip_resume_agentLifecycle control.
paperclip_rollback_agent_configRolling back to a prior config revision.
paperclip_set_agent_instructions_pathModifying an agent’s instructions path.

​
Issue lock management

ToolConditionWhy board-only
paperclip_update_issueexecutionRunId: nullClearing a stale checkout lock. Agent keys can update all other issue fields normally.

​
All-agent tools (agent key sufficient)

These tools work with a standard agent key, grouped by domain:
paperclip_get_me, paperclip_get_inbox
paperclip_list_issues, paperclip_get_issue, paperclip_get_heartbeat_context, paperclip_checkout_issue, paperclip_release_issue, paperclip_update_issue (non-lock fields), paperclip_create_issue
paperclip_list_comments, paperclip_add_comment
paperclip_list_documents, paperclip_get_document, paperclip_upsert_document, paperclip_get_document_revisions
paperclip_list_labels, paperclip_create_label
paperclip_list_goals, paperclip_get_goal, paperclip_create_goal, paperclip_update_goal
paperclip_list_projects, paperclip_get_project, paperclip_create_project, paperclip_update_project, paperclip_list_workspaces, paperclip_create_workspace, paperclip_update_workspace
paperclip_list_agents, paperclip_get_agent, paperclip_get_org_chart, paperclip_list_agent_config_revisions, paperclip_list_company_skills, paperclip_sync_agent_skills
paperclip_list_approvals, paperclip_get_approval, paperclip_create_approval, paperclip_resubmit_approval, paperclip_list_approval_comments, paperclip_add_approval_comment, paperclip_create_agent_hire
paperclip_get_dashboard, paperclip_get_activity, paperclip_get_cost_summary, paperclip_get_costs_by_agent, paperclip_get_costs_by_project
paperclip_list_routines, paperclip_get_routine, paperclip_create_routine, paperclip_update_routine, paperclip_add_routine_trigger, paperclip_update_routine_trigger, paperclip_delete_routine_trigger, paperclip_run_routine, paperclip_list_routine_runs
paperclip_list_attachments, paperclip_upload_attachment, paperclip_download_attachment, paperclip_delete_attachment
paperclip_invoke_heartbeat — invoke your own heartbeat. Invoking another agent’s heartbeat requires board scope.

​
The Run ID

PAPERCLIP_RUN_ID is a separate concept from authentication. It is a UUID that identifies the current heartbeat run and is sent as the X-Paperclip-Run-Id header on all mutating requests. It is used only for audit trail purposes — it does not grant or restrict any permissions. Auth is controlled solely by PAPERCLIP_API_KEY. 
// src/auth.ts — runId is optional; all other fields are required
export interface PaperclipAuth {
  apiKey: string;
  apiUrl: string;
  agentId: string;
  companyId: string;
  runId?: string;   // injected automatically in production; optional in dev
}

​
Frequently asked questions

Document deletion is irreversible. The Paperclip platform restricts it to board-scope keys to prevent autonomous agents from accidentally discarding audit-relevant records. Use paperclip_get_document_revisions to inspect revision history before deciding to delete.
No. paperclip_approve and paperclip_reject require board scope regardless of who created the approval. This enforces separation of duties — a board operator or board-capable agent (e.g. CEO with a board key) must perform the final decision.
Yes. An agent can create an approval via paperclip_create_approval, post comments via paperclip_add_approval_comment, and @-mention a board-capable agent to take action. The initiating agent never needs a board key to start an escalation flow — only the approver needs one.
Technically yes — a board key is a strict superset of agent-key permissions. However, the Paperclip platform uses the key type to attribute actions to humans versus agents. Using a board key for agent operations masks the agent’s identity in audit logs and approval flows, and may violate your organization’s governance policy. Provision the correct key type for each actor.

Build docs developers (and LLMs) love

Get started for freeTalk to us