# MCP server

> **Who this is for:** App Store Operator users who want to read and manage their App Store apps from an AI app (Claude, ChatGPT, Cursor, Claude Code, VS Code and others that support MCP), and the AI agents they hand this page to. It covers connecting, what the AI app can see and do, the tools, limits, revoking and troubleshooting.

---

## For AI coding agents: read this first

You are connecting an AI app to App Store Operator's MCP server, or using its tools.

- **Server URL:** `https://api.app-store-operator.com/mcp` (Streamable HTTP). Sign-in is OAuth in the browser: the user approves the connection on App Store Operator's own page. There is no API key or token to paste; never ask the user for their password or App Store Connect key.
- **Setup:** use the snippet for the user's AI app in [§3](#3-connect-your-ai-app). If the user's app is not listed, add the URL as a remote MCP server with OAuth.
- **Live App Store changes take two calls** ([§6](#6-live-app-store-changes-two-steps)). The first call returns a preview and a confirm code and changes nothing. Show the preview to the user and call again with `confirm` only after they say yes. Never confirm on your own.
- **Figures** are exactly what the user's dashboard shows; each tool's description gives the units. Do not invent data the tools did not return (search volumes, rankings).
- **Check your work end to end:** after connecting, call `whoami` and tell the user which account, workspace and access (read only, or read and change) the connection has. Then call `list_apps` to show the connection works.
- **Errors** are plain English sentences: relay them to the user in their language ([§11](#11-troubleshooting)).

---

## 1. Quick facts

| | |
|---|---|
| Server URL | `https://api.app-store-operator.com/mcp` |
| Transport | Streamable HTTP, stateless (`POST` only) |
| Sign-in | OAuth 2.1 with PKCE and dynamic client registration; you approve each connection on App Store Operator's consent page |
| Access | **Read only** or **Read and change**, chosen by you on the consent page |
| Tools | 40: apps, metadata, versions, review submission, reviews, screenshots, analytics, events and funnels ([§7](#7-tools)) |
| Saved prompts | `aso_audit`, `reply_to_reviews`, `weekly_report` ([§8](#8-prompts)) |
| Limits | 120 tool calls a minute and 30 live App Store changes an hour, per connection ([§9](#9-limits)) |
| Manage connections | Dashboard → **Settings** → **AI apps** |

## 2. Before you start

- An App Store Operator account, with at least one App Store Connect connection if you want the AI app to see apps.
- An AI app that supports remote MCP servers with OAuth sign-in.
- The server URL. It is also in the dashboard under **Settings** → **AI apps**, with a **Copy** button.

## 3. Connect your AI app

Add the server URL to your AI app as below. The first time the AI app uses it, it opens App Store Operator in your browser to approve the connection ([§4](#4-approve-the-connection)).

### 3.1 Claude

In Claude (web or desktop): **Settings** → **Connectors** → **Add custom connector**, paste `https://api.app-store-operator.com/mcp` and add it. Then select **Connect** on the new connector to sign in.

### 3.2 ChatGPT

In ChatGPT: **Settings** → **Connectors**, add a custom connector and paste `https://api.app-store-operator.com/mcp`. Custom connectors are not available on every ChatGPT plan; if you don't see the option, check OpenAI's help for your plan.

### 3.3 Claude Code

Run this in a terminal:

```bash
claude mcp add --transport http app-store-operator https://api.app-store-operator.com/mcp
```

Add `--scope user` to use it in every project, not only the current one. Then, inside Claude Code, run `/mcp`, choose `app-store-operator` and sign in. The saved prompts appear as slash commands, for example `/mcp__app-store-operator__weekly_report`.

### 3.4 Cursor

Add the server to `mcp.json`: `~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` in one project.

```json
{
  "mcpServers": {
    "app-store-operator": {
      "url": "https://api.app-store-operator.com/mcp"
    }
  }
}
```

Cursor then shows the server in its MCP settings; sign in from there when it asks.

### 3.5 VS Code

Add the server to `.vscode/mcp.json` in your project (or to your user MCP configuration), then start it from the file or the MCP server list and sign in when asked:

```json
{
  "servers": {
    "app-store-operator": {
      "type": "http",
      "url": "https://api.app-store-operator.com/mcp"
    }
  }
}
```

### 3.6 Other AI apps

Any AI app that supports remote MCP servers over HTTP with OAuth can connect: add `https://api.app-store-operator.com/mcp` as the server URL. App Store Operator registers the app automatically during sign-in; there is no client ID or secret to set up.

## 4. Approve the connection

When the AI app connects, your browser opens App Store Operator's consent page. Sign in to the dashboard if asked. The page shows:

- the AI app's name and the address it will send you back to;
- your account and the workspace the connection will use;
- the access to give: **Read only** or **Read and change** ([§5](#5-what-the-ai-app-can-see-and-do)).

Select **Allow** to connect, or cancel to connect nothing. After **Allow**, go back to your AI app. We also email you that an AI app was connected, with a link to **Settings** → **AI apps**, so you notice a connection you did not make.

Only allow AI apps you trust. Each connection works in one workspace, the one shown on the consent page. To use another workspace, connect again while that workspace is selected in the dashboard.

## 5. What the AI app can see and do

**Read only**

- Your account's email address and name, and your workspace.
- Your apps, their metadata, versions, drafts and change history.
- Customer reviews, including reviewers' nicknames and text.
- App Store analytics, with Apple's sales and proceeds estimates.
- Events data and funnels, including the identifiers and device details your apps send.
- The status of your App Store Connect connections (never the key itself).

**Read and change**: everything in Read only, plus:

- In App Store Operator only: edit metadata drafts, restore a past value into a draft, discard a draft, create, edit and delete funnels, start syncs, and recheck a connection.
- In App Store Connect: create a new version (not visible to App Store users until it is submitted and released).
- **On the live App Store**, each with the two-step confirm ([§6](#6-live-app-store-changes-two-steps)): push metadata, submit a version for review or remove it from review, reply to a review or delete a reply, reorder or delete screenshots.

An AI app never receives your App Store Connect key or your password. It cannot add or remove App Store Connect connections or delete your account, and it works only within the permissions your role in the workspace gives you. In **History**, a change made through an AI app is marked with the app's name (for example "via Claude").

What the AI app reads goes to the company that provides it, which handles it under its own terms and may process it outside your country. Our privacy policy explains this: https://app-store-operator.com/privacy

## 6. Live App Store changes: two steps

Tools that change what App Store users see (`push_draft`, `submit_for_review`, `cancel_submission`, `reply_to_review`, `delete_review_reply`, `reorder_screenshots`, `delete_screenshot`) never act on the first call:

1. The AI app calls the tool. App Store Operator changes nothing and returns `status: "not_changed_yet"`, a **preview** of the change and a **confirm code**.
2. The AI app shows you the preview and asks you.
3. Only after you agree, it calls the same tool again with the same input plus the confirm code. Then the change is made.

A confirm code works once, for 10 minutes, for that tool with exactly that input. If the input changes or the code expires, the AI app must ask for a new preview. Metadata pushes are kept in **History**, so you can restore an earlier value; review replies and screenshot changes cannot be undone from App Store Operator.

## 7. Tools

**Access**: *read* tools work on every connection; *change* tools change App Store Operator (or start work in App Store Connect) and need **Read and change**; *live* tools also change the live App Store and use the two-step confirm. A read-only connection does not list change and live tools at all.

| Tool | Access | What it does |
|---|---|---|
| `whoami` | read | The account and workspace this connection acts for, and its access |
| `list_apps` | read | Your apps across every App Store Connect connection, with their ids |
| `get_app` | read | One app's overview: versions and their states, ratings, setup state |
| `list_versions` | read | An app's live version and any in progress, with draft edit counts |
| `get_metadata` | read | A version's store listing per locale: live value, draft value, editable or not |
| `preview_draft` | read | What pushing the draft would change, diffed against live App Store Connect values |
| `get_push_status` | read | Progress of a push, per locale and field |
| `get_submission` | read | Whether a version can be sent to App Review, the blocking issues and the builds to choose from |
| `list_history` | read | Changes to store listings, newest first, with previous and new values |
| `get_sync_run` | read | Status of a background sync, version creation or submission |
| `sync_app` | change | Re-reads an app's versions and metadata from App Store Connect |
| `create_version` | change | Creates a new iOS App Store version in App Store Connect |
| `update_draft` | change | Saves values into a version's draft; nothing reaches the App Store until a push |
| `discard_draft` | change | Deletes a version's unpushed draft |
| `restore_change` | change | Puts a past value from History back into the draft |
| `push_draft` | live | Sends the draft's values to App Store Connect |
| `submit_for_review` | live | Attaches a build and submits the version to App Review |
| `cancel_submission` | live | Takes a version waiting for App Review back out of review |
| `list_reviews` | read | An app's written reviews with any developer reply, filterable by rating and reply state |
| `get_analytics` | read | App Store analytics for a period: totals, previous period, daily figures, sources, territories |
| `get_visuals` | read | An app's versions and the newest version's screenshots in the primary locale |
| `list_screenshots` | read | A version's screenshots in one locale, read live from App Store Connect |
| `list_connections` | read | Your App Store Connect connections, their status and last error |
| `revalidate_connection` | change | Checks a connection's API key with Apple again |
| `sync_reviews` | change | Fetches an app's newest reviews from App Store Connect |
| `reply_to_review` | live | Publishes or replaces a developer reply to a review |
| `delete_review_reply` | live | Deletes the developer reply to a review |
| `reorder_screenshots` | live | Puts one screenshot set in a new order |
| `delete_screenshot` | live | Deletes one screenshot from an editable version |
| `get_event_catalog` | read | Every event name an app has sent, with property keys and counts |
| `get_event_trends` | read | How often events happened over time, as event counts or distinct people |
| `get_recent_events` | read | The newest 100 raw events, as on the Live view |
| `get_event_usage` | read | Your account's events this month against its plan limit |
| `list_funnels` | read | An app's saved funnels |
| `get_funnel` | read | One saved funnel's definition |
| `run_funnel` | read | A saved funnel's result over a date range |
| `preview_funnel` | read | An unsaved funnel's result, to try it before saving |
| `create_funnel` | change | Saves a new funnel, shared with the workspace |
| `update_funnel` | change | Changes a saved funnel |
| `delete_funnel` | change | Deletes a saved funnel; its events are kept |

## 8. Prompts

### 8.1 Saved prompts

The server offers three saved prompts. Your AI app lists them where it shows MCP prompts (in Claude Code, as slash commands):

| Prompt | Arguments | What it does |
|---|---|---|
| `aso_audit` | `appId`, optional `locale` | Audits an app's listing against ASO best practice and gives prioritised changes. Changes nothing unless you ask |
| `reply_to_reviews` | `appId`, optional `rating` (e.g. `1,2`) | Drafts replies to unanswered reviews in each review's language and sends only the ones you approve |
| `weekly_report` | optional `appId` | A short report of the last 7 days against the 7 before: traffic, conversion, downloads, proceeds, reviews, changes, a funnel and 3 actions. Read only |

### 8.2 Example prompts

You can also just ask. For example:

- "Which of my apps had the most impressions last month, and how did their conversion change?"
- "Show the unanswered 1- and 2-star reviews of Barmly from the last two weeks and draft replies. Don't send anything yet."
- "Compare the English and German subtitles and keywords of my newest app, and suggest better ones with character counts."
- "Put the new What's New text into the draft for every locale, then show me the diff before pushing."
- "Is version 2.4 ready to submit for review? What is blocking it?"
- "Build a funnel from onboarding_started to purchase_completed with a one-day window and show last week's result. Don't save it."
- "How many events have we used this month, and which app sends the most?"

## 9. Limits

Each connection can make:

- **120 tool calls a minute**, and
- **30 live App Store changes an hour** (counted when a change is confirmed, not at the preview).

Apple allows each App Store Connect API key about 3,500 calls an hour, shared with your dashboard's syncs; these limits keep one AI app from using them all up. Over a limit, the tool answers "Limit reached" with the seconds to wait.

## 10. Revoke a connection

Dashboard → **Settings** → **AI apps** → **Connected apps** lists each connection with its access, when it was connected and when it was last used. Select **Revoke** to end one: the AI app loses access at once. To use it again, connect it again from the AI app.

A connection also ends on its own:

- after **90 days** without use;
- when you reset your password (every connection ends);
- when your account is deleted or disabled.

Signing out of the dashboard does not end a connection, and removing App Store Operator in the AI app may not end it on our side. To be sure, revoke it in **Settings** → **AI apps**. Revoking stops further access but does not remove data the AI app's provider already received; ask the provider for that.

## 11. Troubleshooting

| Symptom | Cause and fix |
|---|---|
| The AI app says "Sign in to App Store Operator again" or asks to re-authenticate | The connection ended (revoked, 90 days unused, password reset) or its sign-in expired. Reconnect from the AI app |
| "This AI app isn't registered with App Store Operator" on the consent page | Remove App Store Operator from your AI app and add it again |
| "This connection request doesn't match the AI app that started it" or "This connection link doesn't work" | The sign-in link was changed or is incomplete. Start the connection again from your AI app |
| "This connection can only read" | The connection is Read only. Revoke it in **Settings** → **AI apps**, reconnect and choose **Read and change** |
| The change tools are missing | Same cause: a read-only connection does not list them |
| "Limit reached: this connection can make…" | Over a limit ([§9](#9-limits)). Wait the seconds the message gives |
| "This confirm code is invalid, already used, expired, or was given for a different change" | The AI app must call the tool again without `confirm`, show you the new preview and ask you again |
| `list_apps` returns nothing | The workspace has no App Store Connect connection yet, or the connection is in another workspace. Check `whoami` and the dashboard |
| A tool reports an error from Apple | Check the connection with `list_connections`; after fixing the key in the dashboard, run `revalidate_connection` |
| An app or figure looks out of date | Run `sync_app` (metadata, versions) or `sync_reviews` (reviews). Apple's analytics run about two days behind |
| "Something went wrong on App Store Operator's side" | Try again in a moment. If it keeps happening, contact support with the request ID from the message |

## 12. Technical details for MCP client developers

- **Protected resource metadata** (RFC 9728): `https://api.app-store-operator.com/.well-known/oauth-protected-resource/mcp`. A request without a valid token gets `401` with a `WWW-Authenticate: Bearer resource_metadata="…"` header pointing to it.
- **Authorization server metadata** (RFC 8414): `https://api.app-store-operator.com/.well-known/oauth-authorization-server`.
- **Dynamic client registration** (RFC 7591): `POST https://api.app-store-operator.com/oauth/register`. Public clients only (`token_endpoint_auth_method: none`). Redirect URIs must be `https`, `http` on a loopback address, or a private-use scheme with a dot (such as `cursor.app:`).
- **Authorization**: `https://api.app-store-operator.com/oauth/authorize`, authorization code with PKCE `S256` only. The response includes `iss` (RFC 9207).
- **Tokens**: `POST https://api.app-store-operator.com/oauth/token` with `authorization_code` or `refresh_token`. Access tokens last 1 hour. Refresh tokens rotate on every use; reusing one ends the whole connection.
- **Endpoint**: `POST /mcp` with `Authorization: Bearer <access token>`. The server is stateless: there is no session and no server-sent event stream, so `GET` and `DELETE` answer `405`.
- **Tool annotations**: read tools have `readOnlyHint: true`; live tools have `destructiveHint: true` and an extra optional `confirm` argument.
