---
name: auth-help
description: Walk through PinAppAI MCP authentication — recommend the browser-flow login first, fall back to manual config + env-var auth for advanced cases.
arguments: []
---
# PinAppAI MCP authentication setup

Detect the user's host AI client from prior context (Claude Code, Cursor,
Codex CLI, Continue, Claude Desktop, etc.). Tailor the steps below to
that client.

## Step 1 — Recommended: browser sign-in (no key copy/paste)

For interactive setups (laptop, dev workstation), the cleanest path is
the two-line install:

```bash
npx @pinappai/mcp install   # registers MCP entry in detected AI client configs
npx @pinappai/mcp login     # opens browser, mints a per-machine key, saves locally
```

`install` writes `mcpServers.pinappai = {command, args}` into every
detected client config (Claude Code, Cursor, Claude Desktop, Codex CLI,
Continue) — no env block, no secret. `login` then opens the user's
default browser to a workspace picker, mints a fresh `ppk_` key named
`Claude Code CLI · <hostname>`, and saves it to
`~/.config/pinappai/credentials.json` (mode 0600). The MCP server
reads it from there at startup.

After both commands complete, restart the AI client and the
`/pinappai:…` slash commands should appear.

If the browser flow doesn't work (SSH session, headless server,
container without a display), the CLI prints the URL + user-code so
the user can open it manually on another machine. Otherwise fall
back to step 2.

## Step 2 — Fallback: manual config with explicit key

For CI / headless / container installs, or when the user explicitly
wants to pin a key inline, walk them to https://app.pinappai.com/api-keys.
Tell them to click "Generate API key", name it after the machine /
context, pick the workspace, and copy the `ppk_…` plaintext (shown
once).

Then either:

**Use as env var (CI / scripts):** set `PINAPPAI_API_KEY=ppk_…` in the
environment that spawns the MCP. The MCP server reads it from env
first, the credentials file second.

**Or pin inline in the AI client's MCP config:** pick the block matching
the host:

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

**Cursor:** edit `~/.cursor/mcp.json`:
```json
{ "mcpServers": { "pinappai": { "command": "npx", "args": ["-y", "@pinappai/mcp"], "env": { "PINAPPAI_API_KEY": "ppk_..." } } } }
```
Restart Cursor.

**Codex CLI:** edit `~/.codex/config.toml`:
```toml
[mcp_servers.pinappai]
command = "npx"
args = ["-y", "@pinappai/mcp"]

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

**Continue:** edit `~/.continue/config.yaml`:
```yaml
mcpServers:
  - name: pinappai
    command: npx
    args: ["-y", "@pinappai/mcp"]
    env:
      PINAPPAI_API_KEY: ppk_...
```

**Claude Desktop:** edit `~/Library/Application Support/Claude/claude_desktop_config.json`
with the same shape as Cursor.

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

## Step 3 — Verify

Call `get_me()` FIRST and report the identity to the user — after an
account switch, "it works" is not enough; they need to see WHO it works
as. Lead the verification report with a line like:

> Signed in as **<name> <email>** — workspace **<workspace name>**
> (<slug>, your role: <role>).

Then call `list_projects()`. Successful response = working setup. On error,
surface the error code (`auth_invalid_key`, `auth_revoked`, etc.) and
suggest:

- For `auth_invalid_key`: re-run `npx @pinappai/mcp login`, OR confirm
  the env-var key is intact.
- For `auth_revoked`: same — the key was revoked from the dashboard;
  the user needs a fresh one.
- For `not_found` on a specific project: run `list_projects` to see
  what's accessible to this key.
- If prompts behave oddly after a PinAppAI update (e.g. a slash command
  references a tool that doesn't exist): reconnect the pinappai MCP
  server (or restart the AI client) — a long-running server can outlive
  its own package version; a fresh start realigns code and prompts.

## Sign out / switch accounts

`npx @pinappai/mcp logout` deletes the credentials file. `npx
@pinappai/mcp login` again starts a fresh flow (workspace picker,
fresh key). Old keys remain visible (and revocable) at
app.pinappai.com/api-keys.

NEVER log or echo back the user's plaintext key, even partially beyond
the `ppk_…` prefix. If the user pastes a malformed key, do NOT
proceed — explain what's wrong and re-link to step 1.

{{include: _shared/output-language.md}}