# Paperclip Setup > Configure local operator assumptions for working with Paperclip through paperclipai and Paperclip MCP fallback. Use when setting up this repo, checking Paperclip CLI context, installing project-local or explicitly global MCP config, or preparing the Paperclip operator skill suite. - Skill: `bbengamin/paperclip-setup` (Agent Skill, multi-file: 18 files) - Install (CLI): `npx skillmds@latest add bbengamin/paperclip-setup` - Raw SKILL.md: https://api.skillmd.com/api/skills/bbengamin/paperclip-setup/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: bbengamin (https://skillmd.com/u/bbengamin) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/bbengamin/paperclip-setup --- # Paperclip Setup Prepare the local operator environment for the Paperclip skill suite. ## References Read these first: - Packaged shared docs: - `references/CONTEXT.md` - `references/docs/paperclip-operator/control-plane.md` - `references/docs/paperclip-operator/workflow.md` - `references/docs/paperclip-operator/cli-contract.md` - `references/docs/paperclip-operator/integration-matrix.md` - Bundled templates when project docs are missing: - `references/project-docs/AGENTS.md` - `references/project-docs/CLAUDE.md` - `references/project-docs/CONTEXT.md` - `references/project-docs/docs/paperclip-operator/control-plane.md` - `references/project-docs/docs/paperclip-operator/workflow.md` - `references/project-docs/docs/paperclip-operator/afk-readiness.md` - `references/project-docs/docs/paperclip-operator/cli-contract.md` - `references/project-docs/docs/paperclip-operator/integration-matrix.md` - `references/project-docs/docs/paperclip-operator/paperclip-docs-index.md` - `references/project-docs/docs/growth-operator/workflow.md` - `references/project-docs/docs/growth-operator/control-plane.md` - `references/project-docs/docs/growth-operator/afk-readiness.md` ## Workflow 1. Inspect the local Paperclip CLI. ```sh command -v paperclipai paperclipai --version paperclipai context show --json ``` 2. If `paperclipai` is missing, guide a fresh install. First check whether the environment can install the npm package: ```sh command -v node node --version command -v npm npm --version ``` If Node.js and npm are present, tell the operator to install the CLI globally. `paperclipai` is the official first-party Paperclip CLI; supply-chain scanners flag this global install as they would any package install: ```sh npm install -g paperclipai ``` Then verify the binary is on `PATH`: ```sh command -v paperclipai paperclipai --version ``` If install succeeds but `command -v paperclipai` still fails, inspect npm's global binary directory and tell the operator to add it to `PATH`: ```sh npm bin -g ``` Do not run a global install without operator approval. If Node.js or npm are missing, ask the operator to install Node.js for their platform first, then rerun setup. 3. If the CLI is installed, continue setup instead of stopping at the first failing Paperclip command. Treat setup as a ladder: - CLI installed and on `PATH` - CLI can read its context - API base is reachable - auth is configured - company context is selected - Paperclip MCP config is installed or intentionally skipped - shared operator docs exist A failure at one rung should produce the next concrete command or decision needed, not a generic blocker report. 4. Verify the configured API base before trying company reads. Inspect the active context: ```sh paperclipai context show --json ``` If the API base is missing, empty, or only the unreachable default, ask the operator for the Paperclip environment URL before attempting auth or company commands. Phrase this as a setup input, for example: ```text What Paperclip environment URL should this CLI use? For example: https://paperclip.example.com or http://localhost:3100. ``` When the operator provides a URL, verify it before writing context: ```sh curl -fsS /api/health ``` If it is reachable, show the proposed context mutation and ask for approval. Before any `context set`, read the current context so existing values can be preserved: ```sh paperclipai context show --json ``` ```sh paperclipai context set --api-base --use ``` If the operator wants an isolated or named profile, include `--profile ` before `--use`. Treat `context set` as replacing the profile's configured values rather than merging unknown existing fields: when both API base and company id are known, set them together in one command. If the API base is `http://localhost:3100`, verify the local Paperclip API is actually running: ```sh curl -fsS http://localhost:3100/api/health ``` If the API health check fails, report that install is complete but the Paperclip API server is not reachable. Ask whether the operator wants to start the local Paperclip API or provide a different Paperclip environment URL. Do not treat this as an auth failure until the API is reachable. 5. If the API is reachable but auth or context is missing, guide login and context selection. ```sh paperclipai auth login --api-base paperclipai company list --json paperclipai context show --json ``` If no company is selected after login, ask the operator which company to use. Do not guess across companies. 6. Inspect available companies if Paperclip auth is configured. ```sh paperclipai company list --json ``` 7. Confirm the active company scope. If no company is selected, ask the operator which company to use. Do not guess across companies. When the operator selects a company, preserve the API base while writing the company id: ```sh paperclipai context set --api-base --company-id --use paperclipai context show --json ``` Verify the resulting profile contains both `apiBase` and `companyId`. If it does not, repair by setting both values together and read the context back again. 8. Verify Paperclip MCP config. Paperclip MCP uses `@bbengamin/paperclip-mcp-server` as a fallback surface after CLI. MCP is not required for skills to load; it is needed only when Paperclip operations need the MCP fallback surface. For Codex, default to project-local Codex configuration in the current trusted project: ```text .codex/config.toml ``` For Claude Code, default to project-local Claude MCP configuration in the current trusted project: ```text .mcp.json ``` Use global or user-level configuration only when the operator explicitly asks for it: ```text ~/.codex/config.toml ``` Inspect the intended target before proposing a change: ```sh test -f .codex/config.toml && sed -n '1,220p' .codex/config.toml test -f ~/.codex/config.toml && sed -n '1,220p' ~/.codex/config.toml test -f .mcp.json && sed -n '1,220p' .mcp.json ``` Proposed Codex project-local TOML: ```toml [mcp_servers.paperclip] command = "npx" args = ["-y", "@bbengamin/paperclip-mcp-server"] ``` Proposed Claude Code project-local command: ```sh claude mcp add paperclip -s project -- npx -y @bbengamin/paperclip-mcp-server ``` This writes the equivalent `.mcp.json` entry: ```json { "mcpServers": { "paperclip": { "command": "npx", "args": ["-y", "@bbengamin/paperclip-mcp-server"] } } } ``` If the operator wants explicit host-local overrides, include only the requested environment values: ```toml [mcp_servers.paperclip.env] PAPERCLIP_API_URL = "" PAPERCLIP_COMPANY_ID = "" ``` Prefer token-free configuration that falls back to the active `paperclipai` profile and board auth. Do not write `PAPERCLIP_API_KEY` into project-local config. If a bearer token is required, ask the operator to use a local environment variable or user-level config. Before writing MCP config, show: - target scope: project-local or global - target path - exact TOML table, Claude command, or JSON entry - whether the `paperclip` MCP entry will be created, replaced, or left unchanged Ask for explicit approval before editing the config file. After writing, verify: ```sh sed -n '1,220p' claude mcp get paperclip npm view @bbengamin/paperclip-mcp-server version ``` Then tell the operator to restart Codex or Claude Code, or start a new thread/session, before expecting Paperclip MCP tools to appear. Do not treat missing MCP tools in the same running thread as install failure unless a restarted session still cannot load them. 9. Verify shared docs exist. Required files: - `AGENTS.md` - `CLAUDE.md` - `CONTEXT.md` - `docs/paperclip-operator/control-plane.md` - `docs/paperclip-operator/workflow.md` - `docs/paperclip-operator/afk-readiness.md` - `docs/paperclip-operator/cli-contract.md` - `docs/paperclip-operator/integration-matrix.md` - `docs/paperclip-operator/paperclip-docs-index.md` - `docs/growth-operator/workflow.md` - `docs/growth-operator/control-plane.md` - `docs/growth-operator/afk-readiness.md` 10. If docs are missing, propose scaffolding them. Show the exact files that will be created or updated. Ask for approval before writing. Use bundled templates from `references/project-docs/`. Create missing directories as needed. If a target file already exists, do not overwrite it silently. Summarize the conflict and ask whether to skip, merge manually, or replace. 11. Report setup status. Include: - whether `paperclipai` was found or install guidance was given - CLI path and version - active profile - API base - API reachability and whether the next action is starting the local API or changing API base - company id, if configured - auth state or next auth command needed - MCP install scope, target path, and whether restart/new thread is needed - docs created, docs skipped, or remaining missing docs - unresolved setup questions ## Mutation Rule This skill may read freely. Ask before changing CLI context, creating Paperclip records, installing or changing Paperclip MCP config, installing Paperclip company skills, or editing shared docs. Creating missing shared docs from bundled templates is allowed only after operator approval.