# Connect this agent to AppBrain

You are setting up the AppBrain MCP server for the user you are working with. Follow these steps.

AppBrain has data on Google Play apps: keyword rankings over time, competitors, app metadata,
download estimates, and the SDKs an app uses. Connecting it lets you answer questions like "which
keywords is my competitor beating me on in Germany?" without the user leaving the conversation.

## 1. Add the server

The endpoint is:

```
https://api.appbrain.com/mcp
```

It uses OAuth 2.1, so there is no API key to ask the user for. Add it the way your own client adds a
remote MCP server over HTTP. For example:

- **Claude Code** — `claude mcp add --transport http appbrain https://api.appbrain.com/mcp`
- **Cursor** — add an entry to `~/.cursor/mcp.json` with `"url": "https://api.appbrain.com/mcp"`
- **Anything else** — whatever your client calls a "remote" or "HTTP" MCP server. Do not ask the
  user for a token; the sign-in flow provides one.

If you are not sure how your client registers a remote MCP server, say so and ask the user to add it
through their client's own UI, rather than guessing at a config file.

**Tell the user to restart their client.** Most clients, Claude Code included, only load MCP servers
at startup, so a server added from inside a running session does not show up until the next one. In
Claude Code, have the user exit and start `claude` again, then run `/mcp`, select `appbrain` and
choose to authenticate. A restart ends this conversation, so before stopping, tell the user
to ask the new session to call `whoami` (step 3).

## 2. Send the user to sign in

Once the client has loaded the server, the first call returns `401` with a `WWW-Authenticate`
header, and your client should open a browser at AppBrain automatically. Tell the user what to expect, because they have decisions
to make on that screen:

- **Permissions.** Three, each independently tickable: read keyword and app data; track and untrack
  keywords; export earnings, billing and promotion reports. Only the first is needed for questions.
  Leave the others unticked unless the user wants you to make changes or read financial reports.
- **Developer accounts.** They tick every account you should be able to see. A developer with
  several accounts should tick all of them if they want to ask about their whole portfolio.
- **Which account pays.** Only asked when more than one account is ticked. App data tools cost API
  credits; this picks whose credits.

They can change all of it later at https://www.appbrain.com/oauth/connections.

## 3. Check it worked

Call the `whoami` tool. It returns every account the connection covers, which one pays, the
permissions granted, and any active subscriptions. Report that back to the user in plain language,
naming the accounts, so they can see the connection matches what they intended.

## Things worth knowing before you use the tools

- **Some tools cost credits.** `app_info` costs 1 credit; `app_search` and `app_browse` cost 4 plus
  2 per 10 results beyond the first 10. Keyword tools are free. Keep result limits small unless the
  user asks for more, and say when a request will be expensive.
- **`partner_id` picks the account.** Only needed when the connection covers more than one; without
  it a call uses the account the user nominated. `whoami` lists the ids.
- **A rank of 0 never appears.** "Not ranked" is an absent field, not a zero. Do not infer position
  zero from a missing rank.
- **Tracked keywords are capped** on the free tier. If a write fails on the cap, tell the user what
  the cap is rather than retrying.
- **If a tool returns an error, read it.** They are written for you: they say what was wrong and
  what a valid value looks like. Correct the argument and retry rather than giving up.

Full documentation: https://www.appbrain.com/docs/api/mcp