Skip to content
AppGazers

DEVELOPER REFERENCE

MCP tools reference for ASO: App Store & Google Play

Research App Store, Google Play and Chrome Web Store listings from your assistant. This reference documents all 37 registered tools, their accepted inputs and example calls. Reading these docs needs no account; calling the server requires authentication.

Set up your assistant · Try the public research tools

Endpoint and authentication

Streamable HTTP endpoint: https://appgazers.com/mcp. Send MCP JSON-RPC requests with POST and accept application/json, text/event-stream. The server is stateless; GET and DELETE are not MCP session operations.

Add the endpoint URL to your MCP client, then sign in with Google and approve OAuth 2.1 access. OAuth uses PKCE S256. Access tokens go in Authorization: Bearer <access_token>. The mcp:read scope reads catalog data; mcp:user additionally allows your watchlist tools. Clients can request offline_access for refresh tokens.

Existing personal tokens (wsk_…) remain a legacy alternative: send one as a Bearer credential or in x-api-key. Existing token-path URLs also work with POST. Prefer OAuth for new connections. Manage your signed-in connections.

Call tools/list to discover tools, then tools/call with the registered name and arguments. Tool results normally contain a JSON string in content[].text; the connector pair also returns structuredContent.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_categories",
    "arguments": {
      "source": "apple_mobile"
    }
  }
}

Use JSON booleans, numbers and arrays in calls. Some underlying Zod inputs also accept query-string spellings through coercion; the parameter tables show the published MCP types. “—” means no schema default, not false or zero.

Plan limits

MCP is available on every plan. Each tool has its own daily allowance, plus one weekly allowance across all tools.

PlanCalls per tool / dayAll tools / week
Free550
Basic100700
Pro3002,500

Days reset at 00:00 UTC. The combined ISO week resets Monday at 00:00 UTC. Every served tool call counts, including cached reads. Failed or refused calls are released along with any charge. Compare plans.

Usage credit past a limit

Basic and Pro can opt in to use credit after either allowance is exhausted. Each over-limit call costs $0.02, or $0.05 for the four live keyword tools: get_keyword_difficulty, batch_keyword_difficulty, find_easier_keywords, suggest_keywords. Crossing both limits charges once. This is the MCP overage price even when a keyword response is cached.

Free cannot spend usage credit past its limits. Paid calls need both opt-in and enough credit; otherwise the call is refused. Failed calls return their usage and any overage charge.

What Free returns

On Free, discovery lists show identities at absolute positions 1–10; rows 11+ are locked, with numbers retained. Revenue estimates and keyword demand/opportunity are hidden. Revenue filters are refused. Paid plans unlock those fields; coverage gaps and unknown values still apply. Explicitly named apps and your own watchlist keep their identities. A locked result is not a missing observation.

Keyword difficulty remains visible, while popularity, traffic and opportunity are hidden. The easier-keyword result hides the terms of its top five suggestions on Free, while candidate scores stay visible; its seed demand scores and opportunity gains are hidden. Estimates are modeled ranges for the recorded period, not reported revenue, profit or exact search counts.

Errors and recovery

HTTP 401 · -32001
Missing, expired or revoked credentials. Follow the WWW-Authenticate discovery challenge and reconnect.
HTTP 403 · -32003
Insufficient scope or denied account access. For watchlist tools, reconnect and approve mcp:user.
HTTP 402 · -32004
A plan allowance was reached, or opted-in usage credit is insufficient. The message names the plan, window, reset time and upgrade URL. Wait for reset, upgrade, or enable/fund usage credit on a paid plan.
HTTP 429 · -32002
The credential’s request-per-minute budget was reached. Respect Retry-After. Live keyword work also has its own caller-based throttle and can return a tool error.
HTTP 503 · -32000
Usage could not be checked or the service is unavailable. Retry after the suggested delay.
Tool and input errors
Read result.isError and the text content as well as top-level JSON-RPC errors. Schema errors identify invalid arguments; handler errors can include bad_input with issues, not_found, search_busy or query_timeout. Correct inputs, narrow an expensive search, or retry transient failures. Never treat an error as an empty result.
{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32004,
    "message": "AI assistant (MCP) allowance reached. Check the reset time or upgrade at https://appgazers.com/pricing."
  }
}

This abridged refusal illustrates the wire shape; the actual message supplies your plan’s window and reset time. Large successful responses can have truncated notes. Continue with returned cursors and narrow the query as instructed; a missing field or null freshness date is not proof of zero activity.

Tool index