paperclipai/paperclip · critical · Error

Missing PAPERCLIP_API_KEY

Error message

Missing PAPERCLIP_API_KEY

What it means

readConfigFromEnv's second required-field check: PAPERCLIP_API_KEY must be a non-empty string, otherwise the client has no credential to put in the Authorization header. Throws immediately after the URL check.

Source

Thrown at packages/mcp-server/src/config.ts:29

}

function stripTrailingSlash(value: string): string {
  return value.replace(/\/+$/, "");
}

export function normalizeApiUrl(apiUrl: string): string {
  const trimmed = stripTrailingSlash(apiUrl.trim());
  return trimmed.endsWith("/api") ? trimmed : `${trimmed}/api`;
}

export function readConfigFromEnv(env: NodeJS.ProcessEnv = process.env): PaperclipMcpConfig {
  const apiUrl = nonEmpty(env.PAPERCLIP_API_URL);
  if (!apiUrl) {
    throw new Error("Missing PAPERCLIP_API_URL");
  }
  const apiKey = nonEmpty(env.PAPERCLIP_API_KEY);
  if (!apiKey) {
    throw new Error("Missing PAPERCLIP_API_KEY");
  }

  return {
    apiUrl: normalizeApiUrl(apiUrl),
    apiKey,
    companyId: nonEmpty(env.PAPERCLIP_COMPANY_ID),
    agentId: nonEmpty(env.PAPERCLIP_AGENT_ID),
    runId: nonEmpty(env.PAPERCLIP_RUN_ID),
  };
}

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Set PAPERCLIP_API_KEY to a valid agent API key from the Paperclip control plane.
2. Confirm the secret is mounted/exported into the MCP server process.
3. Verify the var name is exactly PAPERCLIP_API_KEY.

Example fix

# before
export PAPERCLIP_API_URL=https://paperclip.example.com/api
# PAPERCLIP_API_KEY missing -> error
# after
export PAPERCLIP_API_KEY=$(cat /run/secrets/paperclip-key)

if (!process.env.PAPERCLIP_API_KEY?.trim()) throw new Error('PAPERCLIP_API_KEY must be set before starting the MCP server');

When it happens

Trigger: Server started without PAPERCLIP_API_KEY, or with the var empty/whitespace.

Common situations: API key secret not injected by the secrets manager; key rotated and the new one not yet deployed; var name typo (e.g. PAPERCLIP_KEY).

Related errors

• Missing PAPERCLIP_API_URL
• companyId is required because PAPERCLIP_COMPANY_ID is not se
• agentId is required because PAPERCLIP_AGENT_ID is not set
• Environment variable ${envName} is empty or not set.
• Environment variable ${opts.valueEnv} is empty or unset.

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/2770129786345f98. Report an issue: GitHub.