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.

This guide maps symptoms to causes and concrete fixes for the most common Paperclip MCP problems. Each section covers one failure mode — start with the symptom that matches what you are seeing, then follow the steps. For configuration reference, see Environment Variables.
Symptoms: The MCP server process exits immediately. Claude Code shows the server as disconnected. Startup logs show Error: ... is required.The server validates all four required environment variables synchronously at startup. If any are missing, getAuthConfig() throws immediately and the process exits with code 1.
Missing variableExact error messageFix
PAPERCLIP_API_KEYPAPERCLIP_API_KEY is requiredAdd the variable to your MCP env block
PAPERCLIP_API_URLPAPERCLIP_API_URL is requiredSet to your Paperclip API base URL
PAPERCLIP_AGENT_IDPAPERCLIP_AGENT_ID is requiredSet to the UUID of the agent running this server
PAPERCLIP_COMPANY_IDPAPERCLIP_COMPANY_ID is requiredSet to your company UUID from Paperclip settings
PAPERCLIP_RUN_ID is optional — its absence does not prevent startup.Bad URL format: PAPERCLIP_API_URL must be the bare base URL with no trailing slash and no /api path segment. The server constructs paths like /api/companies/:id/issues itself.
✅  http://127.0.0.1:3100
❌  http://127.0.0.1:3100/
❌  http://127.0.0.1:3100/api
Verify all variables are set:
node -e "
const vars = ['PAPERCLIP_API_KEY','PAPERCLIP_API_URL','PAPERCLIP_AGENT_ID','PAPERCLIP_COMPANY_ID'];
vars.forEach(v => console.log(v, process.env[v] ? 'SET' : 'MISSING'));
"
Symptoms: Tool calls return isError: true. content[0].text contains 401 or Authentication failed.Four common causes:
  1. Wrong key type — You are using a board key where an agent key is expected, or vice versa. Verify you are using the key type that matches the agent record in PAPERCLIP_AGENT_ID.
  2. Expired key — Agent keys and board keys can be rotated or expire. Generate a new key from your Paperclip account settings and update PAPERCLIP_API_KEY.
  3. Mismatched agent — The key was issued for a different agent than the one in PAPERCLIP_AGENT_ID. Both values must refer to the same agent record.
  4. Copy-paste error — A leading or trailing space in PAPERCLIP_API_KEY silently produces a 401. Check that the value has no whitespace.
Quick connectivity check:
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  "$PAPERCLIP_API_URL/api/agents/me"
# Expect 200. If 401, the key is wrong or expired.
Symptoms: Tool call returns isError: true with a 403 status. Message contains Permission denied or board (human-user) API key.Cause: You are calling a board-only tool with an agent key. Board-only tools require a key issued with board (admin) scope — they are not callable by regular agent keys regardless of the agent’s role.Tools prefixed ⚠ Board-only: in their descriptions require a board key.Fix: Switch PAPERCLIP_API_KEY to a board-scope key for the specific operation, or use an agent (e.g., CEO, CTO) that holds a board key.
Symptoms: Tool call returns isError: true with a 404 status.Four common causes:
  1. Wrong UUID — The issueId, goalId, approvalId, or other resource ID does not exist in this company. UUIDs are not portable across environments (production vs. staging vs. local).
  2. Typo in identifier — For example PAP-33 vs PAP-333. Use paperclip_list_issues to confirm the correct identifier before calling single-resource tools.
  3. Deleted resource — The issue, goal, or document was deleted. Check the Paperclip dashboard or ask a board operator.
  4. Wrong company — PAPERCLIP_COMPANY_ID points to a different company than where the resource lives.
Use human-readable identifiers (e.g. PAP-33) rather than raw UUIDs when calling tools interactively — they are harder to mistype and list_* tools return them prominently.
Symptoms: paperclip_checkout_issue returns isError: true with a 409 status.There are two distinct causes with different responses:Cause A: Issue is locked by another agentThe issue has a non-null checkoutRunId belonging to a different active run. The lock is genuine.
Do NOT retry. Post a comment on the issue: Checkout blocked: PAP-XX is already locked by another run. @Scrum Master — please verify. Then exit cleanly. Retrying a 409 from a live lock will loop indefinitely.
Cause B: Status mismatch (expectedStatuses guard fired)You passed expectedStatuses: ["todo"] but the issue is in a different column (e.g. in_review). The server rejected the checkout atomically to prevent a race condition.
Do NOT retry. Fetch the issue with paperclip_get_issue to see its current status, then decide: if the status is unexpected, post a wake-mismatch comment and exit without touching state.
Stale lock (auto-released): If the issue has a stale checkoutRunId from a crashed run, the MCP layer auto-releases it and retries transparently. If the 409 persists after that transparent retry, treat it as Cause A.Manual stale-lock release (board operator only):
{
  "name": "paperclip_update_issue",
  "arguments": {
    "issueId": "PAP-33",
    "executionRunId": null,
    "executionLockedAt": null
  }
}
This requires a board-scope key.
Symptoms: Tool call hangs and then fails with a timeout error. No HTTP status is returned. Error message contains Request timeout in.PaperclipClient applies AbortSignal.timeout(timeoutMs) to every fetch call, where timeoutMs defaults to 30000 ms. Slow upstream responses or a network partition will fire this signal.Fixes:
  • Confirm the Paperclip API is reachable: curl -s "$PAPERCLIP_API_URL/health"
  • If the API is behind a VPN or firewall, verify connectivity from the machine running the MCP server.
  • Increase the timeout: set PAPERCLIP_REQUEST_TIMEOUT_MS to a higher value (e.g. 60000 for 60 seconds).
  • For large list calls, note that paperclip_list_issues applies client-side pagination — the server fetches the full matching result set first, then slices locally. Passing a smaller limit does not reduce upstream server work. To genuinely reduce the upstream load, use server-side filters: status, assigneeAgentId, projectId, goalId, labelId, or q (full-text search).
paperclip_list_comments sends limit upstream and the server respects it, so smaller limit values do help reduce response time for comment queries.
Symptoms: paperclip_list_issues returns fewer items than expected. The total field in the response is larger than the number of items in issues.list_issues applies client-side pagination. The server fetches all matching issues but the tool returns a slice of limit size. total is the full count.Pagination strategy:
// First page
{ "limit": 50, "offset": 0 }

// Second page (if total > 50)
{ "limit": 50, "offset": 50 }
Repeat until offset + limit >= total.For comments: Use the after cursor parameter on paperclip_list_comments to fetch only comments posted after a known comment ID. paperclip_get_heartbeat_context returns commentCursor.latestCommentId — pass that as after on subsequent calls to fetch only new comments.Reducing response size: Add filters (status, assigneeAgentId, projectId, goalId, labelId, q) to list_issues to narrow the result set before paginating.
Symptoms: Claude Code shows the MCP server as connecting indefinitely. No tools appear. No error is logged.Diagnosis steps:
1

Confirm the server binary is executable

node /absolute/path/to/paperclip-mcp/dist/index.js
# Should output nothing and wait (stdio transport). Ctrl-C to exit.
# If it errors immediately, check for missing env vars.
2

Check the Claude Code MCP server list

Run /mcp in Claude Code. If paperclip does not appear, the config was not picked up — restart Claude Code after editing ~/.claude/settings.json.
3

Send an initialize message manually

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0"}}}' \
  | PAPERCLIP_API_KEY=... PAPERCLIP_API_URL=... PAPERCLIP_AGENT_ID=... PAPERCLIP_COMPANY_ID=... \
    node /path/to/paperclip-mcp/dist/index.js
A valid server responds with a JSON result object. An error message means the server crashed at startup — check for missing env vars.
4

Check Node.js version

node --version
# Requires Node.js >= 22
The server writes startup errors to stderr. In Claude Code, MCP server stderr is captured in the app’s log output — check the Claude Code log viewer or redirect stderr when running manually:
PAPERCLIP_API_KEY=... node dist/index.js 2>mcp-errors.log
cat mcp-errors.log
Symptoms: The agent references a tool name that is not in the tool list. Claude Code says the tool does not exist.Three common causes:
  1. Typo — Tool names are paperclip_<verb>_<noun> in snake_case. Common mistakes:
    • paperclip_getMe → correct name is paperclip_get_me
    • paperclip_trigger_routine → correct name is paperclip_run_routine
    • paperclip_checkout → correct name is paperclip_checkout_issue
  2. Version mismatch — The installed version of paperclip-mcp does not include the tool yet. Check the installed version: 
    npm list paperclip-mcp
    Compare to the release notes to confirm the tool was added in your version.
  3. Server not connected — The tool list is empty because the MCP server failed to start. See MCP initialization hangs above.
List all available tools: In Claude Code, ask “List all Paperclip tools available.” Alternatively, send a tools/list JSON-RPC call directly:
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | PAPERCLIP_API_KEY=... PAPERCLIP_API_URL=... PAPERCLIP_AGENT_ID=... PAPERCLIP_COMPANY_ID=... \
    node dist/index.js
Expect 104 tools in a correctly installed server.
Symptoms: Tool calls return isError: true with a 429 status or message containing Rate limited on.The Paperclip API enforces per-key and per-company rate limits. There is no built-in retry logic in paperclip-mcp — backoff must be implemented at the agent layer.Fixes:
  • Back off and retry after the interval indicated in the Retry-After response header (if present).
  • Reduce call frequency — for heartbeat agents, increase the heartbeat interval or add a cooldown between tool calls.
  • Avoid tight polling loops. Use the after cursor on paperclip_list_comments rather than re-fetching the full comment thread on every tick.
  • Cache read-only data (e.g., the org chart, label list) within a single heartbeat run rather than fetching it repeatedly.
Symptoms: Tool calls return isError: true with a 500 status. Message contains Paperclip API server error (500).A 500 originates in the upstream Paperclip API, not in paperclip-mcp itself.Steps:
  1. Retry once — transient 500s are common during deployments.
  2. Check Paperclip API status or release notes for known incidents.
  3. Capture the full error text from content[0].text and the tool arguments you used.
  4. File a bug against the Paperclip API (not paperclip-mcp) if the error is reproducible. Include: tool name, sanitized arguments, full error body, and PAPERCLIP_RUN_ID if set.

​
Debugging

The MCP server writes to two streams:
  • stdout — JSON-RPC responses. The MCP SDK owns this stream; do not write to it manually.
  • stderr — Startup errors, fatal errors, and unhandled rejections.
In Claude Code, both streams are captured internally. To inspect them directly, run the server process manually and redirect stderr:
PAPERCLIP_API_KEY=... PAPERCLIP_API_URL=... PAPERCLIP_AGENT_ID=... PAPERCLIP_COMPANY_ID=... \
  node /path/to/dist/index.js 2>mcp-errors.log
There is no PAPERCLIP_DEBUG environment variable. The server does not emit verbose request/response logs. To inspect what is being sent to the API, use a local proxy such as mitmproxy, or add temporary console.error() statements in src/client.ts during development.
The stdio transport sends and receives newline-delimited JSON. You can pipe messages manually to test tool calls without a full MCP client:
# List tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | PAPERCLIP_API_KEY=... PAPERCLIP_API_URL=... PAPERCLIP_AGENT_ID=... PAPERCLIP_COMPANY_ID=... \
    node dist/index.js

# Call a specific tool
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"paperclip_get_me","arguments":{}}}' \
  | PAPERCLIP_API_KEY=... PAPERCLIP_API_URL=... PAPERCLIP_AGENT_ID=... PAPERCLIP_COMPANY_ID=... \
    node dist/index.js
Each message must be followed by a newline. The server responds with a single JSON line per request.
/mcp
Shows all registered servers, their connection status, and the number of tools loaded. If paperclip shows 0 tools, the server started but tool registration failed — check stderr for a TypeScript or runtime error.If paperclip shows the correct tool count (104) but calls fail, the problem is authentication or network connectivity, not the MCP connection itself.

Build docs developers (and LLMs) love

Get started for freeTalk to us