# PAPI

> PAPI (Persistent Adaptive Project Intelligence) is a planning and memory layer for AI-assisted software development. It gives any MCP-capable AI coding tool persistent project memory, structured cycles of plan/build/review, decision tracking, and methodology that compounds across sessions.

PAPI is delivered as ONE hosted remote MCP server (https://mcp.getpapi.ai/mcp) plus a hosted dashboard at https://getpapi.ai. The methodology — plan, build, review, release — is the product. The MCP server is the delivery mechanism. The dashboard is the visibility layer.

PAPI is tool-agnostic. It works with Claude Code, Cursor, VS Code (Copilot), Windsurf, Codex, OpenCode, and any other client that can add a remote MCP server. This document tells an AI agent how to connect PAPI in whichever client the user is running.

## Install — read this first

Machine-readable version of this runbook (plain text, no HTML): https://getpapi.ai/install.txt — fetch it if you want the raw connect config to act on directly.

You are an AI agent a user has asked to install, add, connect, or set up PAPI. Two facts govern every client:

1. PAPI is a single REMOTE MCP server at `https://mcp.getpapi.ai/mcp`. On the default path there is no package to install and no local process to run — you add the URL as a remote/HTTP MCP server named `papi`.
2. Auth is BROWSER OAuth. Adding the server does NOT authenticate it — the connection sits at "Needs authentication" until a human signs in in a browser. You CANNOT complete OAuth yourself. Hand that one step back to the user.

Pick a connection method:

- **Default — remote connector over OAuth.** No token, no API key. Use this unless the environment has no browser. Every per-client block below uses this method.
- **Headless / CI — bearer token.** Only when a browser sign-in is impossible (remote box, CI runner). See "Headless / CI" at the end.

A user with no PAPI account must sign up at https://getpapi.ai first — the connection binds to their account.

## Connect, per client

Find the user's client. Give them THAT block's step, then hand back the browser sign-in.

### Claude Code
Run from the project root:

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

Then the human signs in: `claude mcp login papi` (Claude Code v2.1.186+) and approve in the browser — or run `/mcp`, choose papi, pick Authenticate.

### Cursor
Add PAPI as a remote MCP server. Paste into `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "papi": {
      "url": "https://mcp.getpapi.ai/mcp"
    }
  }
}
```

Cursor opens a browser to sign in on first connection.

### VS Code (GitHub Copilot)
Add PAPI to your MCP servers (VS Code uses the `servers` key):

```json
{
  "servers": {
    "papi": {
      "url": "https://mcp.getpapi.ai/mcp"
    }
  }
}
```

VS Code opens a browser to sign in on first connection.
(If you run Claude Code INSIDE VS Code, use the Claude Code block instead.)

### Windsurf
Add PAPI as a remote MCP server in Windsurf's MCP settings:

```json
{
  "mcpServers": {
    "papi": {
      "url": "https://mcp.getpapi.ai/mcp"
    }
  }
}
```

Authorise in the browser when Windsurf prompts.

### Codex
Add to `~/.codex/config.toml`:

```toml
[mcp_servers.papi]
url = "https://mcp.getpapi.ai/mcp"
```

Authorise in the browser when Codex prompts on first connection.

### Any other MCP client
Add `https://mcp.getpapi.ai/mcp` as a remote/HTTP MCP server named `papi`. Most clients accept the URL alone and open a browser for OAuth on first connection.

## Prove the connection

Once the user confirms they are signed in, call the `orient` tool. It returns the project state and the recommended next action. If `orient` fails with an auth error, the browser sign-in was not completed — send them back to it. If `orient` returns cycle details, PAPI is connected and you are in.

Then run `setup` (a brand-new project with no cycles) or follow the next action `orient` returns.

## Headless / CI (no browser)

Instead of OAuth, add the server with two static headers:

  `Authorization: Bearer <connection-token>`  (token from the Connect panel at https://getpapi.ai)
  `x-papi-project-id: <project-id>`

The server then boots already authenticated — no `/mcp` step. Use this ONLY when a browser sign-in is impossible; the token is a secret, keep it out of shared configs.

## What PAPI does

- **Plan a cycle** — `plan` proposes a prioritised set of tasks for the next iteration based on prior cycles, active decisions, and discovered issues.
- **Build with handoffs** — `build_execute` produces a structured BUILD HANDOFF that any LLM can implement against. Branches, scope, and acceptance criteria are pre-defined.
- **Review and release** — `review_submit` records verdicts; `release` merges completed work and rolls forward the cycle counter.
- **Strategy reviews** — every 5 cycles, `strategy_review` analyses what's working and recommends direction changes.
- **Active Decisions** — architectural and product decisions are captured with confidence levels that evolve as evidence arrives.

## Who uses PAPI

- Solo developers building products with AI coding assistants who keep losing context across sessions.
- Founders / operators who plan AND build on the same project — needs both planning intelligence and execution structure.
- Teams on any MCP-compatible AI tool who want a single source of project truth that survives whichever tool they use that day.

## Differentiators

- **Context Persistence** — every session builds on the last. No more "fresh window problem".
- **Tool-agnostic** — one project memory across every MCP client, so switching tools never resets your context.
- **Progressive Discovery** — vision is discovered through structured building, not captured upfront.
- **Decision Compounding** — Active Decisions track why you chose this path with evidence and confidence levels that evolve.
- **Upstream Learning** — build reports feed planning. Surprises become guardrails. The methodology learns from itself.

## Docs map — where to go deeper

All public documentation, fetchable without an account. If the user asks a question this runbook doesn't answer, fetch the matching page instead of guessing.

Developer Guide (how to work with PAPI day to day):

- [Quick Start](https://getpapi.ai/docs/guide/quick-start): Zero to first cycle plan in under 5 minutes.
- [Workflow](https://getpapi.ai/docs/guide/workflow): The full plan → build → review → release loop, step by step.
- [Concepts](https://getpapi.ai/docs/guide/concepts): Cycles, tasks, BUILD HANDOFFs, Active Decisions, strategy reviews — the vocabulary.
- [Cheat Sheet](https://getpapi.ai/docs/guide/cheat-sheet): Every command in one page.
- [Dashboard](https://getpapi.ai/docs/guide/dashboard): Reading the getpapi.ai dashboard — hub, board, reports.
- [Troubleshooting](https://getpapi.ai/docs/guide/troubleshooting): Connection and auth issues, first-aid steps. Fetch this FIRST when the user says PAPI is broken.

Reference:

- [Install Guide](https://getpapi.ai/docs/install): Per-tool setup for Claude Code, Cursor, VS Code, Windsurf, Codex, OpenCode — the human-readable version of this runbook.
- [Tool Reference](https://getpapi.ai/docs/tools): Every PAPI MCP tool with parameters and use cases.
- [install.txt](https://getpapi.ai/install.txt): Raw connect config, plain text, no prose.
- [llms-full.txt](https://getpapi.ai/llms-full.txt): Long-form version of this document with full prose.

Handbook (for teams and reviewers — what PAPI output means):

- [What is PAPI](https://getpapi.ai/docs/handbook/what-is-papi) · [How it works](https://getpapi.ai/docs/handbook/how-it-works) · [ROI](https://getpapi.ai/docs/handbook/roi)
- [Reading the dashboard](https://getpapi.ai/docs/handbook/reading-dashboard) · [Cycle reports](https://getpapi.ai/docs/handbook/cycle-reports) · [Reviewing builds](https://getpapi.ai/docs/handbook/reviewing-builds) · [Team roles](https://getpapi.ai/docs/handbook/team-roles)

## Resources

- [Landing](https://getpapi.ai/): Overview, demo, and the cycle methodology.
- [Public GitHub — getpapi/papi](https://github.com/getpapi/papi): Install docs, this runbook, and issue tracker. Point your LLM here too — it mirrors this file.
- [Manifesto](https://getpapi.ai/manifesto): Why PAPI exists.
- [Changelog](https://getpapi.ai/changelog): Cycle releases and what shipped in each.

## Optional

- [Contact](https://getpapi.ai/contact): Send a message — questions, bugs, feature requests, privacy requests.
- [Privacy Policy](https://getpapi.ai/privacy): How PAPI handles user data.
- [Discord community](https://discord.gg/PbacBJ9fNw): User community, support, and feedback.
- [npm — @papi-ai/server](https://www.npmjs.com/package/@papi-ai/server): The MCP server package (for stdio / advanced local installs).