> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appstack.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Connect Claude to your Appstack Analytics data: installs, ad spend, revenue, and attribution, over MCP.

<Note>
  **Beta.** MCP access is opt-in per organization right now. If a project's MCP key won't generate, or the OAuth connect flow says "not enabled for your organization," ask an Appstack admin to turn it on for your org.
</Note>

Appstack's MCP server lets Claude (or any MCP-compatible client) query your app's attribution and analytics data directly, including installs, ad spend, revenue, and campaign performance, scoped to a single project.

## Prerequisites

* An Appstack account, with MCP access enabled for your organization (beta, so ask an admin).
* A project in Appstack (bundles up to one iOS + one Android app) whose data you want to query.

## Connect via OAuth (Claude Desktop, Claude.ai, ChatGPT desktop)

This is the self-serve, recommended path, with no key to copy or store.

**Claude Desktop / Claude.ai:**

1. Go to **Settings → Connectors → Add custom connector**.
2. Paste the server URL: `https://mcp.appstack.tech/mcp`
3. Log in with your Appstack account when prompted.
4. Pick the project you want to grant access to (auto-selected if you only have one eligible project).

**ChatGPT desktop:**

1. Go to **Settings → Plugins → Add → Add a MCP server**.
2. Name it, set the type to **Streamable HTTP**, and paste the server URL: `https://mcp.appstack.tech/mcp`
3. Save, then click **Authenticate** and log in with your Appstack account.

Both discover everything else automatically (client registration, PKCE, token issuance), so there is nothing to configure manually. Appstack staff logging in with a platform-admin account see an "all organizations" consent screen instead of a project picker.

## Connect via API key (Claude Code, scripts)

Each project has its own MCP key, generated from that project's settings page in the Appstack dashboard (**Project → Settings → MCP**). The key only exposes that project's data.

```bash theme={null}
claude mcp add --transport http appstack-analytics \
  https://mcp.appstack.tech/mcp \
  --header "Authorization: Bearer <YOUR_PROJECT_MCP_KEY>"
```

Or in Claude Desktop's config file:

```json theme={null}
{
  "mcpServers": {
    "appstack-analytics": {
      "url": "https://mcp.appstack.tech/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_PROJECT_MCP_KEY>"
      }
    }
  }
}
```

Regenerate the key any time from the same settings page. This immediately invalidates the old one.

## Get better results with a skill

Claude can use these tools with no extra setup, but it has to guess the right
call order and exact metric/dimension names on its own. Installing the
[`appstack-mcp` skill](https://github.com/appstack-tech/appstack-skills)
teaches it those conventions up front, so you get fewer wasted calls and no
made-up measure names.

```bash theme={null}
claude plugin marketplace add appstack-tech/appstack-skills
claude plugin install appstack@appstack-plugins
```

See the [appstack-skills README](https://github.com/appstack-tech/appstack-skills) for Codex and Cursor install instructions.

## Available tools

| Tool                                                                      | What it does                                                                                                                                                                                                       |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `whoami`                                                                  | Identify which app(s) the connection has access to, each with its own organization. Call this first.                                                                                                               |
| `find_organization`                                                       | Search organizations by (partial) name, with each match's apps. Only relevant for Appstack staff, since platform-admin access spans every organization with no other way to look one up by name.                   |
| `list_metrics`                                                            | List the metrics and dimensions available to query.                                                                                                                                                                |
| `list_dimension_values`                                                   | List valid values for a dimension (countries, media sources, app names, and so on) before filtering on it.                                                                                                         |
| `query_metrics`                                                           | Run a scoped query with measures, dimensions, filters, and a date range, and get real numbers back.                                                                                                                |
| `list_integrations`                                                       | Every integration (ad network, MMP, subscription platform, and so on) connected to your apps/projects, with its current status.                                                                                    |
| `get_onboarding_checklist`                                                | Completion of the five onboarding steps for a project.                                                                                                                                                             |
| `list_dashboards` / `get_dashboard`                                       | Saved dashboards and their widgets' configured measures/dimensions/filters.                                                                                                                                        |
| `list_user_journeys` / `get_user_journey_filters` / `get_user_journey`    | Per-user event timelines, the "Appstack ID history" for a specific user.                                                                                                                                           |
| `create_link` / `list_links` / `get_link` / `update_link` / `delete_link` | **Write.** Create, read, update, and delete standard links. Ad-network links aren't supported here, so manage those from the dashboard. These are the only tools that change anything; everything else only reads. |

Ask things like:

* *"What was our ROAS by media source last month?"*
* *"Show me installs and revenue by country for the last 30 days."*
* *"What are the possible values for media\_source?"*
* *"Is our RevenueCat integration connected and active?"*
* *"Create a standard link for this app with campaign name 'summer-promo'."*

## Troubleshooting

**"MCP isn't enabled for your organization yet."**
MCP is in beta, opt-in per organization. Ask an Appstack admin to turn it on.

**The OAuth consent screen doesn't show the project I expected.**
Only projects in organizations with MCP access enabled appear in the picker, and only ones you're a member of.

**A tool call returns an error instead of data.**
Call `whoami` first to confirm which app(s) are actually in scope for your connection, and `list_metrics` / `list_dimension_values` before guessing measure or dimension names. A made-up name fails rather than silently returning nothing.

## Limits & notes

* Requests are rate-limited per credential (120 req/60s by default). A `429` response includes a `Retry-After` header.
* OAuth access tokens are short-lived (\~1 hour) and refresh automatically, so never copy-paste one.
* A project's MCP key only exposes that project's data (up to one iOS + one Android app), never the rest of your organization.
* Regenerating a project's key immediately breaks any client still using the old one.
* `create_link`/`update_link`/`delete_link` actually change data, so review what Claude is about to do before confirming, same as you would for any tool with write access.