Install Guide

Get started with PAPI

Connect PAPI to your AI coding tool. Run your first cycle plan in under 5 minutes.

Your code stays on your machine. PAPI adds a planning layer to whatever you're already building, it doesn't read your source.

Prerequisites

An MCP-compatible AI tool — Claude Code, Cursor, VS Code (Copilot Chat), Windsurf, OpenCode, Amazon Q CLI, or any tool supporting the MCP protocol.

Node.js 18+ — Required to run the PAPI server. If you use any of the tools above, you almost certainly already have this. Check with node --version — if it errors, install from nodejs.org.

1. Sign up

Go to getpapi.ai/login and sign in with GitHub (recommended) or email.

The onboarding wizard will ask for your project name and optional repo URL. Once done, you'll see your connection token and project ID — the wizard embeds these directly into the config shown on the next screen.

Your connection token is shown once. If you lose it, go to getpapi.ai/onboard?regen=1 to generate a new one.

2. Connect your tool

Pick your AI coding tool below and copy the config. The default Remote MCP path signs you in through your browser — no token to copy, no placeholders to fill in. Paste it as-is and your tool opens a sign-in tab on first connect. If your workflow needs a local process (network-restricted dev environment, offline use), switch to Local install (advanced).

Paste into Claude Code chat

Please add PAPI as an MCP server. Run this — it works from any directory:

  claude mcp add --transport sse papi https://mcp.getpapi.ai/sse

Claude Code will open a browser tab so I can sign in. After that, call the `setup` tool to scaffold this project, then run `orient` and tell me which cycle this project is on.

Paste this as a chat message in Claude Code. Claude Code installs PAPI itself, opens a browser tab so you can sign in, and then runs setup. No terminal, no token to copy.

Advanced setup — use a connection token instead

Prefer an explicit connection token (for a client that doesn't handle browser sign-in, or to pin a specific project)? Sign in and the dashboard pre-fills this snippet with your real token and project ID. The placeholders below are illustrative.

Paste into Claude Code chat

Please add PAPI as an MCP server. Run this command — it works from any directory:

  claude mcp add --transport sse papi https://mcp.getpapi.ai/sse --header "Authorization: Bearer YOUR_CONNECTION_TOKEN" --header "x-papi-project-id: YOUR_PROJECT_ID"

Then call the `setup` tool to scaffold this project. After setup completes, run `orient` and tell me which cycle this project is on.

Paste this as a chat message in Claude Code. Claude Code installs PAPI itself — no terminal required.

3. First run

After saving your config, restart your MCP client. Then in your AI tool, run these three commands in order:

setup

Initialises PAPI for your project. Generates a Product Brief and scaffolds your workflow.

plan

Generates your first cycle plan — scoped tasks with full BUILD HANDOFFs, ready to build.

build_list

Shows the tasks queued for this cycle. Pick one and start building.

Expected time: install to first plan in under 5 minutes.

What's next

Tool reference →

Every PAPI tool — what it does, when to use it.

Dashboard →

View cycles, tasks, build reports, and decisions at getpapi.ai.

Add another project →

Go to Portfolio → New Project. Same connection token, new project ID.

Discord →

Get help, share feedback, see what others are building.

Troubleshooting

PAPI tools not appearing

Check that both PAPI_PROJECT_ID and PAPI_DATA_API_KEY are set in your config. Restart your MCP client after any config change.

npx: command not found

Install Node.js 18+ from nodejs.org — it includes npx.

Server refuses to start: "Conflicting PAPI configuration"

You have both DATABASE_URL and PAPI_DATA_API_KEY set. PAPI uses one or the other. Remove DATABASE_URL from your shell rc file or .mcp.json env block, or set PAPI_SELF_HOST=1 if you genuinely self-host. Restart your MCP client.

PAPI_PROJECT_ID is wrong (or you switched projects)

Open the project switcher at getpapi.ai/settings, copy the correct project ID, and update PAPI_PROJECT_ID in your .mcp.json. Restart your MCP client.

Stale .mcp.json from a previous setup

Open .mcp.json and delete only the "papi" entry inside the mcpServers object — keep the file and any other MCP servers (github, supabase, etc.) intact. Then paste the fresh papi entry from your install snippet. NEVER delete .mcp.json — other MCP servers share it.

Stuck install — nothing connects no matter what

Open getpapi.ai/settings, find your project, click "Reset connection". This rotates your connection token and gives you a fresh install snippet. Your project data, cycles, and history are preserved. Replace the papi entry in your .mcp.json with the new snippet and restart your MCP client.

Lost your connection token

Open getpapi.ai/settings, find your project, click "Reset connection" — this rotates the old token and shows the new one once. Save it immediately.

Want to start execution over but keep your strategy

Open getpapi.ai/settings, find your project, click "Reset project". This cancels in-flight cycles and tasks but keeps your product brief, decisions, hierarchy, and history.