paperclipai/paperclip · critical · Error

Missing PAPERCLIP_API_URL

Error message

Missing PAPERCLIP_API_URL

What it means

readConfigFromEnv requires PAPERCLIP_API_URL to be a non-empty string (via nonEmpty). Missing, empty, or whitespace-only values throw before any other config is read, so this is the first failure you hit when the MCP server cannot locate the Paperclip API.

Source

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

}

function nonEmpty(value: string | undefined): string | null {
  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
}

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_URL to the Paperclip API base (e.g. https://paperclip.example.com/api or the bare host — normalizeApiUrl appends /api).
2. Confirm the var is exported into the shell/process that starts the MCP server.
3. Check for trailing quotes or spaces in the value.

Example fix

# before
$ paperclip-mcp  # no env
# after
export PAPERCLIP_API_URL=https://paperclip.example.com/api
export PAPERCLIP_API_KEY=sk_...
paperclip-mcp

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

When it happens

Trigger: Starting the paperclip MCP server with PAPERCLIP_API_URL unset, empty, or whitespace; a launcher/docker entrypoint that does not export it.

Common situations: Forgot to copy .env into the runtime; docker-compose missing the env entry; CI secret not injected.

Related errors

• Missing PAPERCLIP_API_KEY
• companyId is required because PAPERCLIP_COMPANY_ID is not se
• agentId is required because PAPERCLIP_AGENT_ID is not set
• At least one allowed spreadsheet ID is required.
• Environment variable ${envName} is empty or not set.

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