# Apphud MCP — setup guide (Claude Code & Cursor)

Connects your AI client to the Apphud MCP server: ~200 `apphud_*` tools over apps,
paywalls, products, customers, events, charts and experiments. Transport:
streamable HTTP; auth: OAuth 2.0 + PKCE via `https://id.apphud.com`.

Pick the **Install** and **Authenticate** sections for your client. Everything
from **Scopes** onward applies to both.

## Install

### Claude Code

```bash
# run from the project directory; --callback-port pins the OAuth redirect
# so re-adds reuse a valid client registration
claude mcp add --transport http --scope local --callback-port 3118 apphud-mcp https://mcp.apphud.com/mcp
```

Scopes: `local` (this project, default) · `project` (`.mcp.json`, committed) ·
`user` (all projects). Tools appear in the **next** session — verify an
`apphud_*` tool exists before claiming the server works.

### Cursor

Add the remote server once. Use **project** config to share with the team, or
**global** config for every workspace.

**Project** — create or edit `.cursor/mcp.json` in the repo root:

```json
{
  "mcpServers": {
    "apphud-mcp": {
      "url": "https://mcp.apphud.com/mcp",
      "auth": {
        "scopes": ["mcp:read", "mcp:write", "mcp:admin"]
      }
    }
  }
}
```

**Global** — same block in `~/.cursor/mcp.json`.

Alternatively: **Cursor Settings → Customize → MCP** → add a remote server with
URL `https://mcp.apphud.com/mcp` (writes the same config). Reload the window or
toggle the server on if tools do not appear immediately.

OAuth redirect for Cursor (desktop): `http://localhost:8787/callback`. For web /
Cloud Agents: `https://www.cursor.com/agents/mcp/oauth/callback`. Apphud’s IdP
must allow these; do **not** use Claude’s `localhost:3118` callback in Cursor.

Tools show up after the server is enabled and authenticated — confirm an
`apphud_*` tool is listed before claiming the server works.

## Authenticate — rules for the agent

### Shared

1. **Never ask for or type the user's password, token, or redirect URL.**
2. **Ask which browser to open, and whether to use a private window** — a
   normal window can silently reuse a live Apphud session (wrong account); a
   private window is opened by the user themselves.
3. After login, run `apphud_me` (identity and granted scopes) and
   `apphud_list_companies` (expected company).

### Claude Code

The CLI may print "paste the redirect URL here" — ignore it: with the browser on
the same machine, the listener on `localhost:3118` finishes login by itself.

Plain `claude mcp login` fails in an agent shell (`stdin isn't a terminal`):

```bash
# sleep keeps stdin open ~5 min while the user finishes login in the browser
(sleep 280) | script -q /dev/null claude mcp login apphud-mcp --no-browser >/tmp/apphud-login.log 2>&1 &
sleep 5 && grep -o 'https://id\.apphud\.com[^ ]*' /tmp/apphud-login.log | head -1
open -a "Google Chrome" "<URL>"   # or the browser the user chose
```

Verify: `claude mcp get apphud-mcp` → `✔ Connected`.

### Cursor

1. **Prefer in-chat OAuth.** If the Apphud server is listed but unauthenticated
   (Customize shows **Connect** / **Needs authentication**, or only an `mcp_auth`
   tool is available), ask the user to approve and run **`mcp_auth`** for that
   server (empty arguments). Cursor opens the browser and completes PKCE; the
   callback is handled by Cursor (`localhost:8787` or the `cursor://` handler),
   not by pasting URLs into the terminal.
2. **Do not** use Claude’s `claude mcp login` or `script`/`sleep` workaround in
   Cursor — that flow is Claude Code only.
3. **Manual fallback:** user clicks **Connect** on `apphud-mcp` under
   **Customize → MCP**, completes login in the browser, then starts a **new**
   agent turn so tools reload.
4. **Verify:** Output panel → **MCP Logs** (no auth errors); call `apphud_me` and
   `apphud_list_companies`. If auth still fails after Connect, remove the server
   from `mcp.json` / Customize, re-add with the install JSON above, and connect
   again (fresh OAuth client registration).

## Scopes

The auth URL always requests `mcp:read mcp:write mcp:admin`; the user can
approve a subset on the consent screen, and `apphud_me` reports the real grant.
A write call on a read-only grant is refused server-side:

```
Not permitted: apphud_update_paywall requires the mcp:write scope, but this
connection only granted mcp:read. This is a permission problem, not an
expired token — retrying will not help.
```

## Troubleshooting

- **`invalid_redirect_uri`** — stale or wrong OAuth client registration.
  - **Claude Code:** `claude mcp remove apphud-mcp -s local`, re-add with the
    install command; the `client_id=` in the printed auth URL should change.
  - **Cursor:** remove `apphud-mcp` from `mcp.json` / Customize, re-add, Connect
    again. Ensure the IdP allows Cursor redirect URIs (see **Install → Cursor**),
    not only `http://localhost:3118/callback`.
- **Wrong account** — a live session may be approved instantly, no login
  prompt: log out / disconnect MCP, re-auth in a private window, compare
  `apphud_me.sub`. Claude: `claude mcp logout apphud-mcp`. Cursor: disconnect
  the server in Customize and run Connect or `mcp_auth` again.
- **Pagination** — `meta.page.next_page` carries a cursor even on the last
  page; fetch it and treat an empty result page as the end.
- **Exports** — `apphud_export_*` email a CSV to the account owner; nothing
  returns to the session.

## Calling the API

Most tools need `company_id` and `app_id`:
`apphud_list_companies` → company uid, then `apphud_list_apps` → app uid.

| Goal | Tools |
|---|---|
| Paywalls | `apphud_list_paywalls`, `apphud_get_paywall` |
| Products / placements | `apphud_list_products`, `apphud_list_placements` |
| Customers + their events | `apphud_count_customers`, `apphud_list_customers`, `apphud_get_customer`, `apphud_customer_events` |
| Analytics | `apphud_search_metrics` → `apphud_chart_options` → `apphud_query_line_chart` / `apphud_query_column_chart` |
| Experiments | `apphud_list_experiments`, `apphud_experiment_analytics` |

ID traps: `apphud_customer_events` takes the customer's full UUID `id`, not the
short `uid`; experiment analytics take the experiment's short `uid`, not its UUID.

## Reference

Endpoint `https://mcp.apphud.com/mcp` · auth `https://id.apphud.com` · scopes
`mcp:read / mcp:write / mcp:admin`.

| Client | OAuth callback |
|---|---|
| Claude Code | `http://localhost:3118/callback` (use `--callback-port 3118` on add) |
| Cursor (desktop) | `http://localhost:8787/callback` |
| Cursor (web / agents) | `https://www.cursor.com/agents/mcp/oauth/callback` |

```bash
# Claude Code only
claude mcp logout apphud-mcp     # then re-auth to change granted scopes
claude mcp remove apphud-mcp -s local
```

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

{
  "mcpServers": {
    "apphud": {
      "type": "http",
      "url": "https://mcp.apphud.com/mcp"
    }
  }
}