paca-setup

name	paca-setup
description	Configure the Paca MCP server for use with Claude Code or Claude Desktop. Use when setting up Paca for the first time, adding or editing the MCP server config, troubleshooting connectivity, or installing the Paca skills globally. Walks the user through prerequisites, config file generation, verification, and optional global skill install.
compatibility	Requires Node.js 18+ and a running Paca instance.

You are helping the user configure the Paca MCP server for their Claude Code environment.

Walk the user through the setup interactively, step by step. Do not dump all instructions at once — confirm each step before proceeding.

---

Setup flow

Step 1 — Check prerequisites

Ask the user to confirm:

• Paca is running (local: http://localhost:8080, or their hosted URL)
• Node.js 18+ is installed (node --version)
• They have a Paca API key (Settings → API Keys inside Paca UI)

If any prerequisite is missing, guide the user to resolve it before continuing.

Step 2 — Identify the Claude Code config file

Ask which environment they want to configure:

A. Claude Code (CLI) — project-level (recommended for team projects) → Create or edit .claude/mcp.json in the project root.

B. Claude Code (CLI) — global → Run: claude mcp add paca --env PACA_API_KEY=<key> --env PACA_API_URL=<url> -- npx -y @paca-ai/paca-mcp

C. Claude Desktop → Edit the config file for your OS:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Step 3 — Generate the config snippet

Based on their choice, generate the exact config block. Example for option A (.claude/mcp.json):

{
  "mcpServers": {
    "paca": {
      "command": "npx",
      "args": ["-y", "@paca-ai/paca-mcp"],
      "env": {
        "PACA_API_KEY": "<their-api-key>",
        "PACA_API_URL": "<their-paca-url>"
      }
    }
  }
}

Substitute the actual values the user provides. Remind them:

• Never commit API keys to git. Add .claude/mcp.json to .gitignore if it contains a key, or use environment variable substitution.

Step 4 — Apply the config

For option A, write the .claude/mcp.json file directly (ask permission first).
For options B and C, show the command/snippet and ask the user to apply it.

Step 5 — Verify

Once configured, ask the user to restart Claude Code / Claude Desktop, then test with:

"List my Paca projects"

If Paca tools appear and return results, setup is complete. If not, check:

1. JSON syntax is valid
2. API key is correct (no extra spaces)
3. Paca API URL is reachable (curl <PACA_API_URL>/api/v1/health)
4. Node.js / npx is in PATH

Step 6 — Install the Paca skill globally (optional)

Offer to run the global skill installer so /paca and related skills are always available:

curl -fsSL https://raw.githubusercontent.com/Paca-AI/paca/master/scripts/install-claude-skill.sh | bash

Review the script before running it — curl | bash executes remote code directly.

---

Environment variables reference

Variable	Required	Description
PACA_API_KEY	Yes	API key from Paca → Settings → API Keys
PACA_API_URL	No (default: http://localhost:8080)	Your Paca instance URL