> For the complete AppRefer docs index, see https://apprefer.com/llms.txt (every page as markdown) or https://apprefer.com/llms-full.txt (all docs in one file).

# AI agents & MCP

Give a coding agent what it needs to install, configure and check AppRefer for you.

No account yet? See [getting access as an agent](#getting-access-as-an-agent). There are three ways in, from simplest to most powerful:

1.  **llms.txt** and **llms-full.txt**: an index of every docs page as markdown, and the whole documentation as one plain-text file, for any agent that can read a URL.
2.  **The REST API** with an organisation API key: what an agent should use to create links, change settings and run release checks on apprefer.com.
3.  **The MCP endpoint**: AppRefer's tools exposed over the Model Context Protocol, with organization keys or OAuth login.

## Getting access as an agent

An agent can ask for an AppRefer account for the person it works for, without ever handling a password. It sends the person's email to `POST /api/agent/access-requests` and gets back a short code and a link. The person opens `apprefer.com/activate`, signs in with Google and taps Confirm, while the agent polls for the result. The full contract, with exact requests and responses, is in [https://apprefer.com/auth.md](https://apprefer.com/auth.md).

> **Waitlist**
>
> Accounts are approved by hand right now, so a confirmed request waits on the waitlist until it is approved. After that, the person creates an organisation API key with only the scopes the agent needs, and the agent uses the [REST API](https://apprefer.com/docs/api.md). Confirming never gives the agent a key by itself.

## llms.txt

[https://apprefer.com/llms.txt](https://apprefer.com/llms.txt) is the index for language models: how an agent gets access, then a link to every docs page as markdown. [https://apprefer.com/llms-full.txt](https://apprefer.com/llms-full.txt) is the whole reference in one plain-text file: SDK set-up for all four platforms, tracking links, integrations, billing, support and the APIs. Paste either URL into your agent's chat, or add it to the project's agent instructions (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules`) so every session starts with it.

Every docs page is also served as markdown: add `.md` to its URL (for example [/docs/quickstart.md](https://apprefer.com/docs/quickstart.md)) or request it with `Accept: text/markdown`.

## A setup prompt for your coding agent

Put your SDK key in `APPREFER_SDK_KEY` and, if the agent should call the API, an organisation key with only the scopes it needs in `APPREFER_API_KEY` (see [scopes](https://apprefer.com/docs/api.md#scopes)). Then paste this:

**Prompt**

```
You are adding AppRefer (attribution, billing and in-app support) to this project.

1. Read https://apprefer.com/llms-full.txt first. It is the complete AppRefer reference.
2. Work out the platform (native iOS, Android, Flutter or React Native) and add the
   AppRefer SDK at version 0.11.0 the way llms-full.txt describes for that platform.
3. Call configure once at app start with the public SDK key from APPREFER_SDK_KEY
   (pk_live_ for release builds, pk_test_ for debug builds). Never put an ak_ key
   in the app: organisation API keys are server-side secrets.
4. When a user signs in, call AppRefer.setUserId(id) and, if the app uses Billing,
   AppReferBilling.logIn(id) with the same id. On sign-out call AppRefer.reset()
   (and AppReferBilling.logOut()), then configure again for the next user.
5. On iOS the SDK reads the App Tracking Transparency status but never shows the
   prompt. If the app asks for tracking, keep that prompt in the app's own flow.
6. For server-side work (tracking links, integrations, readiness checks) use the
   REST API at https://apprefer.com/api/v1 with the key in APPREFER_API_KEY:
   "Authorization: Bearer $APPREFER_API_KEY". Only use the scopes the key has.
7. Before you finish, call GET /api/v1/apps/{appId}/support/readiness and
   GET /api/v1/apps/{appId}/billing/readiness, and tell me what is not set up yet.
   Do not change ad network or billing settings without asking me first.
```

For one app, **Settings → Setup guide** gives company admins a longer prompt tailored to that app's framework and current setup, including Support identity, live context, actions and offer cards (see [Set up with your coding agent](https://apprefer.com/docs/support.md#set-up-with-your-coding-agent)).

> **Keys for agents**
>
> A read-only key (`analytics:read`, `apps:read`, `links:read`, `integrations:read`, `skan:read`) is enough for an agent that reports and checks. Add `links:write` only if it should create tracking links. Revoke the key in the dashboard when the job is done.

## Let your agent sign up

An agent can start a seven-day test workspace immediately, build your setup, and give you a claim link. Sign in with the matching Google email to become its owner. Live mode opens after waitlist approval, or immediately when signup is open.

**POST /api/agent/workspaces**

```json
{ "email": "owner@example.com", "company": "Example Labs", "appName": "Example App", "agent": "Your agent" }
```

The response contains `workspace_id`, a one-time `api_key`, `claim_url`, `user_code`, `expires_at`, `mcp_url`, and `test_mode: true`. Keep the key on your server. Poll `GET /api/agent/workspaces/{id}` with it for `unclaimed`, `claimed_pending_approval`, `live` or `expired`.

Unclaimed limits: three apps, twenty links and fifty products; one workspace per email and three per IP each day. Test mode permits sandbox setup and help articles; it blocks live SDK access, integrations, store credentials, Support delivery/AI, web events, web purchases and erasure. Signed Apple sandbox receipts can use the app bundle identifier without live credentials. Google Play verification needs store credentials after claim and approval. Team invites and seats require claim. Unclaimed workspaces expire after seven days; choosing “This wasn’t me” deletes them.

## Connect over MCP (OAuth)

Point an OAuth-capable client at `https://apprefer.com/api/mcp`. A 401 discovers the authorization server through protected-resource metadata. Sign in with Google, select your company, review permissions and allow. Claim a trial workspace first to select it. Manage access under [Settings → Connected agents](https://apprefer.com/dashboard/settings/connected-agents).

Client ID Metadata Documents are supported; rate-limited `POST /api/oauth/register` is the fallback. PKCE S256 and `resource=https://apprefer.com/api/mcp` are required. Redirects match exactly; authorization responses include `iss`. Codes last ten minutes; access tokens one hour; rotating refresh tokens have a thirty-day connection lifetime. Refresh replay revokes the connection. Token and revoke endpoints are `/api/oauth/token` and `/api/oauth/revoke`. The complete wire contract is in [auth.md](https://apprefer.com/auth.md).

## Tools available to organization keys

Use `apps:read/write` for apps, `links:read/write` for links, `integrations:read/write` for integrations, `analytics:read` for reporting, `skan:read` for postbacks, `billing:read/write` for the catalog and metrics, and `support:agent` for help articles. Tools are filtered to your scopes. Company identity comes from the credential; app and link identifiers must belong to it. Platform and cross-company tools are hidden and refused.

Risky tools return `approval_required` and `approval_url` inside their text result. An org admin reviews the action, then the agent repeats the same call with `approval_id` from the URL. Approval lasts 24 hours, works once and is bound to the credential and exact arguments. Integration writes, deleting links and switching Support AI to auto require it. `erase_user` (`users:erase`, explicit environment) and `update_billing_config` (`integrations:write`) also require approval. Trial erasure and store configuration remain refused.

## MCP endpoint

> **Customer and operator credentials**
>
> Customers use `Authorization: Bearer ak_live_...` or an OAuth access token. The operator platform admin key remains supported for cross-company administration; never give it to a customer agent.

|  |  |
| --- | --- |
| Endpoint | `POST https://apprefer.com/api/mcp` |
| Protocol | JSON-RPC 2.0 over HTTP. Each POST is one request and gets one JSON response (no streaming). |
| Methods | `initialize` (protocol version `2024-11-05`, server `apprefer-admin`), `tools/list`, `tools/call` with `{ name, arguments }`. Notifications (`notifications/*`) get an empty `202`. |
| Results | A tool's result is JSON, returned as text in `result.content[0].text`. |
| Errors | `-32700` unreadable JSON, `-32600` not a JSON-RPC 2.0 request, `-32601` unknown method, `-32603` the tool failed (the message says why). |
| GET | 405 Method Not Allowed. Use stateless POST. |
| Time limit | 60 seconds per request (analytics tools query the warehouse). |

### Connect a client

**Claude Code (.mcp.json)**

```json
{
  "mcpServers": {
    "apprefer": {
      "type": "http",
      "url": "https://apprefer.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${APPREFER_API_KEY}"
      }
    }
  }
}
```

**Claude Code (CLI)**

```bash
claude mcp add --transport http apprefer https://apprefer.com/api/mcp \
  --header "Authorization: Bearer $APPREFER_API_KEY"
```

**Cursor (.cursor/mcp.json)**

```json
{
  "mcpServers": {
    "apprefer": {
      "url": "https://apprefer.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:APPREFER_API_KEY}"
      }
    }
  }
}
```

On a self-hosted AppRefer, replace `https://apprefer.com` with your own domain. Keep the key in an environment variable, not in a file you commit.

### Call it directly

```bash
# List the tools
curl -s https://apprefer.com/api/mcp \
  -H "Authorization: Bearer $APPREFER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

# Run a release check
curl -s https://apprefer.com/api/mcp \
  -H "Authorization: Bearer $APPREFER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
        "params": { "name": "get_app_readiness", "arguments": { "appId": "app_3f9c2a1b7d4e" } } }'

{ "jsonrpc": "2.0", "id": 2,
  "result": { "content": [ { "type": "text", "text": "{\n  \"support\": { ... },\n  \"billing\": { ... }\n}" } ] } }
```

## Tools

Every tool the endpoint lists. Most mirror a [REST endpoint](https://apprefer.com/docs/api.md), and secrets are never returned. Ask the agent to call `apprefer_info` first.

### Organisations and apps

| Tool | What it does |
| --- | --- |
| `apprefer_info` | What AppRefer is and the list of tools. Call it first. |
| `list_orgs` | Every organisation on the deployment: id, name, plan, created. |
| `list_waitlist` | People waiting for access: email, company, app link, note, source, approved, signed in (limit, default 200). |
| `approve_waitlist` | Let an email create a company after signing in (email, approved: false to revoke). Doesn't email them. |
| `get_org` | One organisation with its member and app counts (orgId). |
| `list_apps` | An organisation's apps with SDK status (orgId). |
| `get_app` | One app: SDK keys, store URLs, integrations (masked), probabilisticMatching and trackingConsentRequired. It does not return the support AI policy. |
| `create_app` | Create an app (orgId, name, bundleId?, iosUrl?, androidUrl?) and get its SDK keys. |
| `update_app` | Change name, bundleId, store URLs, sdkEnabled (kill switch), trackingConsentRequired, probabilisticMatching or supportAi (replaced whole, so send mode and persona together). |

### Links and integrations

| Tool | What it does |
| --- | --- |
| `list_links` | An app's tracking links with clicks and installs. |
| `create_link` | Create a tracking link (linkId 3 to 50 letters, digits and dashes; network; store destinations; landing page; external campaign ids). |
| `delete_link` | Delete a tracking link. |
| `get_integrations` | An app's integrations and their connection status, secrets masked. |
| `configure_integration` | Set up one integration: meta, google, tiktok, openai, x\_ads (off until enabled: true), apple\_ads, revenuecat, superwall, support (push and email delivery) or gleap (one-time history import). |

### Analytics

| Tool | What it does |
| --- | --- |
| `get_app_stats` | Installs, revenue, trials and purchases with a daily chart (days 1 to 365, default 14). |
| `get_app_overview` | KPIs, network breakdown and top campaigns. |
| `get_campaigns` | Campaign performance, optionally for one network and by ad group, ad, keyword, search term or country. |
| `get_portfolio_stats` | Totals across every app of an organisation. |
| `get_recent_events` | The latest SDK and purchase events of an app (1 to 100). |
| `get_attributions` | Recent install attributions (1 to 500). |
| `get_skan_postbacks` | Summary of Apple's SKAdNetwork and AdAttributionKit postbacks (days 1 to 400, default 30). |

### Billing

| Tool | What it does |
| --- | --- |
| `get_subscription_metrics` | Subscription revenue, trials, conversions, churn, active subscriptions and MRR in USD (start, end, bucket, store, sandbox). |
| `get_billing_catalog` | Entitlements, products, offerings and packages, current offering, placements, targeting rules and experiments. |
| `update_billing_catalog` | Change catalogue sections. Each section sent is replaced whole, so read it first; validated like the dashboard. |
| `get_experiment_results` | Per-variant results of an offering experiment: enrolled, trials, conversion, payers, net revenue, chance to beat control. |

### Support and release checks

| Tool | What it does |
| --- | --- |
| `list_help_articles` | An app's help articles with status (draft or published) and audience (public or agent); body optional. |
| `upsert_help_articles` | Add, edit, publish, unpublish or remove help articles (up to 200 changes). New articles are published and public unless they say otherwise. |
| `publish_help_articles` | Publish articles by slug, or move them back to draft (published: false). |
| `get_app_readiness` | Support readiness (push credentials checked with Apple and Google, email, help centre, AI mode) and billing readiness (mode, stores, which secrets are set, last store notification). refresh: true checks push again. |

The meaning of each setting is on its topic page: [Tracking links](https://apprefer.com/docs/tracking-links.md), [Integrations](https://apprefer.com/docs/integrations.md), [Offerings](https://apprefer.com/docs/offerings.md), [Subscription analytics](https://apprefer.com/docs/subscriptions.md) and [Support](https://apprefer.com/docs/support.md).

---

Source: https://apprefer.com/docs/mcp · Last updated: 2026-10-24