AppScreens MCP Guide

What the MCP does

AppScreens is a curated archive of top app store screenshots, each classified by layout pattern and ASO marketing strategy, with historical versions preserved. The MCP server exposes that archive to AI agents as a small set of read-only tools over Streamable HTTP (POST only) at https://appscreens.store/api/mcp. Instead of scraping the App Store or guessing, your agent gets structured results and direct, fetchable screenshot URLs.

Access requires a Pro plan, whichever way you connect. What differs is the credential: the hosted Claude surfaces obtain an OAuth access token when you approve the connector, and everything else sends a personal ascr_ token generated in Settings → MCP server.

What each surface can do

The tools that carry screenshots hand back image URLs, not images, and whether anything opens a URL is up to the client. The exception is get_screenshot, which returns one screenshot as image data instead — so a client that renders MCP image content can actually look at it. Which clients do is the fact most worth knowing before you start:

In practice: ask Claude to reason from the archive's metadata, classifications, and history, and to call get_screenshot for the one or two screenshots you actually want examined. Asking it to critique an image it was only given a link to will not work — name the tool, or ask a question that can only be answered by looking.

Tool reference

Every tool is read-only. A typical session starts with list_categories / list_tags to discover filter values, then search_apps to find apps, then get_app or get_app_history for screenshots. Six of the seven read the archive; draft_screenshots is the one that hands something back out of it, into the screenshot generator.

Image URLs from get_app and get_app_history are absolute and publicly fetchable, so anything that can make an HTTP request can load them. When you want the screenshot in front of the model rather than linked, use get_screenshot, which returns the image data itself — one screenshot per call, deliberately, so a listing's worth of images never lands in context at once.

Prompt reference

The server also ships three prompts — ready-made research workflows that fix the tool order, the screenshot budget, and the comparisons that would be misleading. Fill in the app or concept and the sequence runs itself, so a good answer stops depending on how well the request was phrased.

MCP prompt arguments are strings, so every value above arrives as text — limit is parsed and clamped, and a platform that names no real store is ignored rather than turned into a filter that matches nothing. Where the prompts appear depends on the client: a client that supports MCP prompts surfaces them in its own prompt or command menu, and one that does not still gets all seven tools — you phrase the request yourself, and the example workflows below spell out what to ask for.

Connect your client

Sign in with your AppScreens account

In claude.ai, Claude Desktop, or Claude Design, open your connector settings, choose to add a custom connector, and paste https://appscreens.store/api/mcp as the server URL. Claude Code reaches the same flow from the terminal — its tab below has the command. Claude then discovers the authorization server, registers itself, and sends you to an AppScreens consent screen; approve it and the tools appear. No credential to store and nothing to update when you rotate a token — and you can cut the connection off again under Connected apps in Settings.

https://appscreens.store/api/mcp

Implementing a client yourself? Discovery starts at the two documents this endpoint publishes: /.well-known/oauth-protected-resource (RFC 9728) names the resource and points at the authorization server, and /.well-known/oauth-authorization-server (RFC 8414) carries its endpoints. Clients are public, PKCE (S256) is required, and only Claude's own callbacks plus RFC 8252 loopback redirects can be registered.

Or connect with a personal token

For Cursor, Codex, and anything else that speaks Streamable HTTP — or for headless and CI use, where no browser can open the consent screen — generate a personal token in Settings → MCP server (Pro required). Your token is shown once — copy it immediately. Then pick your client below and paste the snippet, replacing the placeholder with your token. There is one token per account, so rotating it invalidates every client still holding the old value.

{
  "mcpServers": {
    "appscreens": {
      "url": "https://appscreens.store/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

Any client that supports Streamable HTTP works — the Other tab gives a generic configuration. The endpoint is POST-only and expects an Authorization: Bearer <token> header.

Example workflows

What to ask for when you are driving the tools yourself. The first two have a shipped prompt that does the same job with the guardrails already in place — reach for competitor_teardown or listing_changes if your client offers them, and use these when it does not.

Competitive ASO research

Ask your agent: “Find iOS finance apps that use social proof in their screenshots, and summarize the common layout.” The agent calls list_tags to resolve the social proof strategy slug, search_apps with platform: ios, category: Finance, and the strategy filter, then get_app on the top results to read their metadata and screenshot URLs — and get_screenshot on the two or three whose treatment you actually want described.

One thing to insist on: a strategy filter matches apps tagged from their own screenshots andapps carrying their category's default, so “matched the social proof filter” is not the same claim as “uses social proof”. Tell the agent to check tagSource on each result and report a tag as a finding about that app only when it reads per_app — otherwise say the app sits in a category tagged that way, or go and look at the screenshots.

Tracking a listing over time

Ask: “Show me how Duolingo’s screenshots changed over time.” The agent runs search_apps to find the app, then get_app_history to pull historical snapshots newest-first and describe what changed between versions.

Building your own screenshot set

Ask: “What layout do the top meditation apps lead with? Then draft me a five-slide set for a sleep-tracking app.” The agent researches the category through the read tools, then calls draft_screenshots and hands back a link. Opening it loads the screenshot generator with the captions, layouts, and brand colours in place; you drop in your own screenshots and export every Apple-required resolution.

Two things worth knowing before you use it. The draft carries no image data— the slots arrive empty and you fill them, because the archive holds other companies' screenshots. And if you already have work open in the generator, the link asks before replacing it; there is no undo across a reload, so decline and the draft is simply discarded.

Researching without leaving the design

With the connector added to Claude Design, ask mid-task: “Which ASO strategies do the top 5 meditation apps use? Summarize them as a slide.”Claude resolves the tags and categories through the same tools and writes the answer straight into what you are building. Two habits make it work: state your target resolution as an explicit constraint in the prompt (“1284×2778, portrait”) — the dimensions in the payload will not set the canvas, and a first draft can come back in the wrong orientation — and lead with questions the archive's metadata and tags can answer, naming get_screenshot when you want a specific screenshot pulled in and examined.

Troubleshooting

• “The MCP connector is a Pro feature” on the approval screen — a 402. The AppScreens account you signed in with is on Free. Upgrade (see pricing) and add the connector again; the plan is checked before any credential is issued, so nothing was created in the meantime.
• A tool is missing from the connector— connectors cache their tool list when you connect, so a newly released tool does not appear on an existing connection. Reconnect the connector (or remove and re-add it) and the list refreshes; new tools arrive set to “needs approval” until you allow them.
• Connector added but the tools are never called— adding a connector does not force Claude to use it. Enable it for the conversation in the tools menu, and name the archive in your prompt (“using AppScreens, find…”) until it is habitual.
• Registration or redirect rejected— the authorization server allowlists Claude's own callbacks and RFC 8252 loopback redirects, and nothing else. A hosted third-party client cannot register its callback; use a personal token instead.
• A connector that worked stopped working — access tokens last an hour and clients refresh them silently, so this is usually not expiry. Check Connected apps in Settings: if the connection was revoked there (or with Revoke all), add the connector again and re-approve.
• Screenshots come back as links — expected from the metadata tools: they return absolute image URLs, and the hosted Claude surfaces cite rather than open them. Ask for get_screenshot by name when you want the image itself. See the surface table above.
• “Screenshot N not found” from get_screenshot — sequences are 1-based and belong to the listing's current snapshot. The error names the sequences that do exist; get_applists them alongside each screenshot's URL.
• 401 Unauthorized — the token is missing, malformed, or has been revoked/rotated. Confirm the Authorization: Bearer <token> header is present and matches your current token. If in doubt, rotate in Settings and update your client.
• 403 Forbidden — your account is not on Pro. MCP access requires a Pro plan; see pricing.
• App not found — the id or slug isn't valid. Use search_apps to get current ids and slugs rather than guessing.
• Lost your token — tokens are shown once. Rotate in Settings to get a new one; the old token stops working immediately.

Frequently asked questions