MCP server for AI agents

The PinAppAI MCP server is the AI-native interface to your project. Instead of pasting decision dumps into your editor, your agent runs the apply workflow and walks the full iteration loop end-to-end: read live state, propose code edits, write a marker so the next regeneration knows where the boundary is, and ASK before committing anything.

The MCP server is published as @pinappai/mcp on npm and runs as a stdio server next to the agent. It’s also reachable as a hosted HTTP endpoint, no install required.

Two ways to connect

Way	What it takes	Best for
Hosted connector	One URL, then sign in through your browser (or paste an API key)	any client that speaks MCP over HTTP, zero install
npm package	Two commands: npx @pinappai/mcp install, then login	CI/headless installs, pinning a version, working offline

Both reach the same server: the same 38 tools, the same 10 workflows. Neither is a reduced surface.

Three surfaces, and who uses them

Worth getting straight up front, because they are easy to confuse:

Surface	Who uses it	Example
10 workflows	You invoke them	The apply workflow. How you invoke one depends on your client, see Run a workflow.
38 tools	Your agent calls them over the protocol	list_projects. You never type these.
6 CLI commands	You, in a terminal	npx @pinappai/mcp login

The one mistake worth avoiding: a workflow is not a shell command. Typing pinappai-mcp apply in your terminal will not work. Workflows are invoked inside your AI client.

Hosted connector

For clients that speak MCP over HTTP, connect straight to a hosted endpoint instead of running npx @pinappai/mcp locally.

Endpoint: https://mcp.pinappai.com/mcp (Streamable HTTP).

Two ways to authenticate:

• Browser sign-in, no key to paste. If your client supports MCP browser sign-in (Claude Code does), add the endpoint with no credentials. Your client opens your browser to approve access and pick the workspace the agent works in, then connects. Nothing to copy, nothing to store by hand.
• API key. For clients that authenticate with a static header, pass a bearer key: Authorization: Bearer ppk_.... Mint one from app.pinappai.com/api-keys (see npm package below for what a ppk_ key scopes to).

Either way, a client with no credentials can still discover the server: list tools, read workflows. Running a tool is the part that needs authentication.

Claude Code, browser sign-in

claude mcp add --transport http pinappai https://mcp.pinappai.com/mcp

No key in the command. Your client opens the browser to approve access on first use.

Claude Code, API key

claude mcp add --transport http pinappai https://mcp.pinappai.com/mcp --header "Authorization: Bearer ppk_YOUR_KEY"

Any client with a JSON config (Cursor and similar)

{ "url": "https://mcp.pinappai.com/mcp", "headers": { "Authorization": "Bearer ppk_YOUR_KEY" } }

The npm package (npx @pinappai/mcp) stays fully supported: it’s the right choice for CI/headless installs, pinning a version, or working offline. The hosted endpoint is a second way to connect, not a replacement.

npm package

Two commands work for any AI client (Claude Code, Codex CLI, Cursor, Claude Desktop, Continue):

npx @pinappai/mcp install   # registers the MCP entry in every detected AI client config
npx @pinappai/mcp login     # opens browser for sign-in, mints a per-machine key, saves it locally

install writes the MCP server entry into every AI client config it finds on your machine (~/.claude.json, ~/.cursor/mcp.json, ~/.codex/config.toml, ~/.continue/config.yaml, ~/Library/Application Support/Claude/claude_desktop_config.json). No credential is written at this step.

login runs a browser sign-in flow: prints a URL + a short approval code, opens your browser, lets you pick a workspace if you have multiple, and saves the freshly minted API key locally on your machine. The MCP server picks it up automatically on next launch.

The ppk_… API key is separate from the widget’s pk_* key: it’s a workspace-scoped machine credential, and every call it makes runs with the workspace role of the member who approved the login.

The six CLI commands:

Command	Purpose
npx @pinappai/mcp install	Register MCP entry in every detected AI client config
npx @pinappai/mcp login	Browser sign-in; mint + save a per-machine key
npx @pinappai/mcp logout	Revoke the key server-side and delete the stored credentials file
npx @pinappai/mcp uninstall	Remove MCP entry from AI client configs, and sign out (revoke + delete key)
npx @pinappai/mcp --help	Print every workflow and tool this version exposes
npx @pinappai/mcp --version	Print the installed version

--help reads the live server, so it always describes the version you actually have. It is the one answer to “what can this thing do?” that works identically in every client and every terminal.

Verify the install

Restart your AI client, then ask it, in plain language:

list my PinAppAI projects

If it answers with your projects, the server is connected and authenticated. That check works in every client, because it exercises the tools every client implements.

Do not verify by typing a slash command. Whether workflows appear as slash commands depends entirely on your client, so a slash command that does not autocomplete tells you nothing about whether the install worked. See Run a workflow.

CI / headless installs

The browser-based login doesn’t fit non-interactive contexts. Set PINAPPAI_API_KEY=ppk_… in the environment that spawns the MCP: the MCP server reads env first, then the credentials file. Mint the key from app.pinappai.com/api-keys; name it after the machine / pipeline so you can revoke cleanly later.

Manual install

If you’d rather wire up a single client by hand, or you need to pin a specific version, these are the per-client config snippets the new install writes for you:

Claude Code

claude mcp add-json pinappai '{"type":"stdio","command":"npx","args":["-y","@pinappai/mcp"],"env":{"PINAPPAI_API_KEY":"ppk_..."}}'

Cursor: ~/.cursor/mcp.json

{ "mcpServers": { "pinappai": { "command": "npx", "args": ["-y", "@pinappai/mcp"], "env": { "PINAPPAI_API_KEY": "ppk_..." } } } }

Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

{ "mcpServers": { "pinappai": { "command": "npx", "args": ["-y", "@pinappai/mcp"], "env": { "PINAPPAI_API_KEY": "ppk_..." } } } }

Codex CLI: ~/.codex/config.toml

[mcp_servers.pinappai]
command = "npx"
args = ["-y", "@pinappai/mcp"]

[mcp_servers.pinappai.env]
PINAPPAI_API_KEY = "ppk_..."

Continue: ~/.continue/config.yaml

mcpServers:
  - name: pinappai
    command: npx
    args: ["-y", "@pinappai/mcp"]
    env:
      PINAPPAI_API_KEY: ppk_...

PINAPPAI_API_BASE is optional and defaults to https://api.pinappai.com.

Run a workflow

Workflows ship inside the MCP server. No extra setup.

How you invoke one depends on your client. The MCP spec deliberately leaves that to each client, so there is no single syntax that works everywhere. Find your client:

Your client	Run the apply workflow
Claude Code	Type /pinappai:apply. Typing /pinappai: autocompletes the menu.
Codex	Ask it: “run the pinappai apply workflow”. Codex fetches the procedure and follows it.
Continue (VS Code / JetBrains, agent mode)	Type /apply. Continue lists workflows without a server prefix.
Cursor	Type / and pick from the menu.
Claude Desktop	Use the + menu, then pinappai, then apply.
Any other MCP agent	Ask in plain language, the same as Codex.

Swap apply for any workflow name below.

Two notes worth knowing. Codex does not show workflows as slash commands at all: typing /pinappai: there answers Unrecognized command. Asking in plain language is the supported path, and it runs the same procedure. Continue does not namespace workflows, so ours arrive as /apply, /remove and friends, sharing one menu with any prompt files of your own. Continue also surfaces workflows only in the editor extension in agent mode, not in its cn CLI.

If you are unsure what your client supports, ask it in plain language. That path works everywhere.

The 10 workflows

Workflow	Purpose
setup-project	Create a new project from scratch: workspace, project, widget snippet, reviewers. Offers the no-install review link and bootstraps the iteration boundary marker.
embed-widget	Embed the widget snippet into an existing project’s site and bootstrap the marker, the MCP-native equivalent of “Copy embed prompt for AI”.
apply	The loop’s engine. Drain the Inbox: new applies, reverts for rejected items, rewrites for change requests, then mark the whole round applied in one atomic batch, refreshing /changes/ on the way.
generate-changes-page	Generate the /changes/ review page for a multi-page batch of edits and register its items: for the first page of a big rewrite, or whenever you want one outside an apply run.
remove	Strip widget + /changes/ + helpers when you’re shipping. Preserves .pinappai/ for re-install, and offers to switch off the review link too.
analyze	Read-only triage report on the current CR pile (no edits made).
summarize	Generate a PR description, changelog, or customer email from completed work, citing the original CRs.
audit-review	Summarize recent audit-log activity for the workspace (Business tier; owner role).
auth-help	Diagnose API key / role / scope issues if a tool returns 401 or 403.
reset-project	Wipe a project’s review data back to zero: CRs, decisions, pins, screenshots on the server, optionally the repo’s /changes/ + marker. Not recoverable; asks twice.

npx @pinappai/mcp --help prints this same list from your installed version.

The five featured on /mcp/ (setup-project, embed-widget, apply, generate-changes-page, remove) map to the iteration-loop arc: set up (or embed into an existing site), apply the Inbox, generate the review page, remove when you ship. The other five are utilities you’ll reach for less often.

The iteration loop, at a glance

reviewers pin change requests (#N assigned)
   │
   ▼
Inbox ──── apply workflow ────▶ InReview
  ▲                                 │
  │  Reject / Request change        ├── Approve → Closed
  └─────────────────────────────────┘

Every pin lands in the dashboard Inbox as a numbered change request. One apply run drains it: the agent edits your source, regenerates /changes/, and records the round: every applied CR moves to InReview. Reviewer verdicts either close a CR or bounce it back to the Inbox for the next round, same CR, same #N. There is no separate triage ceremony.

The full state model (substates, defer, reopen, first-action-wins) lives in the iteration loop.

The .pinappai/ directory

A small folder at the root of your repo. It’s load-bearing for the iteration loop: commit it, don’t gitignore it.

File	Purpose
.pinappai/last-applied.json	The iteration boundary marker. ISO timestamp written at end of every apply run. The next /changes/ regen scopes to “git log –since=”.
.pinappai/context.json	Project shape cache: detected stack (Astro / Next / Hugo / etc.), build / lint commands, source dir, route convention, localization shape, and text_lives_in (pages-inline / component-props / i18n-files / content-files / mixed). Saved once, then every prompt reads it instead of re-detecting.

Both files are tiny (a few hundred bytes each). Committing them means a teammate’s first MCP run already knows your project’s shape: no second round of “what stack are you on?” questions per machine.

If .pinappai/ is gitignored or the working tree is read-only, the prompts fall back to in-memory detection: the loop still works, just less efficiently.

Landing-chooser: the AI never auto-commits

Every workflow that touches your repo (setup-project, embed-widget, apply, remove, reset-project) ends with this verbatim block:

✅ <one-line summary>
Affected files: <list including .pinappai/last-applied.json>

How do you want to land this? Pick one:

  (a) New feature branch — suggested name: pinappai/<batch>-YYYY-MM-DD-HHMM
      I'll create the branch from your current HEAD, commit ALL the
      affected files, and either push or stay local — your call.
  (b) Commit on the current branch — same commit, no branch switch.
  (c) Stage only — leave it uncommitted so you can review the diff first.
  (d) Skip — don't touch git, you'll handle it manually.

Suggested commit message: <prefix>(<scope>): <summary>

Tell me which option (a / b / c / d), whether to push, and any
commit-message tweaks. I'll wait.

The agent stops there until you pick. That’s the contract: no git add, no git commit, no git push until you say which option. Branch protection is respected; --no-verify is never used. If you say “your call, just do it,” the default is (b) commit on current branch + don’t push.

Pre-flight is also covered: every applies-to-source prompt runs git status + git branch --show-current before editing. Dirty working tree → it surfaces the diff and asks instead of silently stashing.

Tools the server exposes

38 tools across read + write surfaces. Your agent calls these; you never type them. Here are the 6 read tools you’ll touch most often:

Tool	What it returns
list_projects	All projects the API key can see
list_change_requests	Recent feedback rows (pins, comments, decisions) with filtering by status / kind / page / cursor pagination
get_change_request	Full detail for one feedback row by id: page URL, selector, before/after text, reviewer, decision, screenshot URL
get_review_summary	Aggregate counts: pending vs decided, approved/rejected/change-requested split, per-page breakdown
get_screenshot	The PNG bytes for an attached screenshot, base64-encoded for the agent
analyze_patterns	Across decisions, what wording patterns are reviewers consistently rejecting? Returns clusters with examples

One tool carries the workflows themselves:

Tool	What it does
pinappai_get_workflow	Returns a workflow’s full procedure as text. This is how clients that don’t show workflows as slash commands still run the real thing: the agent fetches the exact procedure and follows it, rather than improvising from the name. It’s what makes “run the pinappai apply workflow” work in Codex. Read-only.

Four tools drive the apply loop (they’re what the apply and generate-changes-page workflows call under the hood):

Tool	What it does
pinappai_list_apply_inbox	Everything Apply-eligible right now: new, rejected (needs a revert), and change-requested (needs new wording), with the fields the agent needs to edit source
pinappai_apply_change_requests	Atomic end-of-round call: takes the per-CR before/after pairs, records one iteration, moves every CR to InReview in a single batch
pinappai_register_change_items	Registers a freshly written /changes/ page’s items with the API so decision bars, the in-page chip, and verdicts light up
pinappai_reset_review_data	The nuclear option behind the reset-project workflow: wipes a project’s CRs, decisions, pins, and screenshots

Two more expose apply history: pinappai_list_iterations (past rounds with their frozen manifests) and pinappai_get_iteration_coverage (how complete is this round: decided vs outstanding, per reviewer).

The remaining 25 cover the full admin lifecycle, and this completes the list of all 38:

Area	Tools
Account & GDPR	get_me, update_me_profile, export_my_data (Art. 15 export)
API keys	list_api_keys, get_api_key, revoke_api_key, restore_api_key
Workspaces	list_workspaces, get_workspace, create_workspace, update_workspace, delete_workspace
Projects	get_project, create_project, update_project, archive_project, unarchive_project
Members	list_members, invite_member, update_member_role, remove_member
Reviewers	list_reviewers, invite_reviewer, revoke_reviewer
Audit log	list_audit_events (Business tier)

Every write is gated by the caller’s role: editor can drive the apply loop and register /changes/ items but not invite members; admin can do everything except permanent-delete (which stays admin-UI-only by design).

Auth model

ppk_ keys are scoped to a workspace, not a single project: one key reaches every project in the workspace. Each key is minted by a workspace member, and every call runs with that member’s current role (viewer / editor / admin / owner): a viewer’s key sees reads only; an admin’s key drives the full lifecycle. Change the member’s role and the key’s reach changes with it; remove the member and the key stops working.

To plug an agent into a second workspace, mint a key there and add the server again under a different name (e.g. pinappai-staging). Multiple servers can coexist; the agent picks based on natural-language context.

Keys can be revoked from admin at any time. The next MCP call from that key returns 401. The agent should treat that as “I lost access, please surface a new key.”

Source

The server source and changelog live at @pinappai/mcp on npm. Bug reports and issues go to the project’s GitHub repo.