Fellow MCP

Introduction

Fellow MCP gives AI clients read-only access to App Store feature data. Use it to compare apps and countries, retrieve screenshots, and build reports. Fellow returns the data; the client handles calculations, charts, and reports.

Requires a Fellow Scale account and a client that supports remote MCP with OAuth. For ChatGPT and Claude setup, see AI Integration.

Connection

Setting	Value
Endpoint	https://app.fellowdev.io/mcp
Transport	Streamable HTTP
Authentication	OAuth Authorization Code with PKCE (S256)
Required scope	fellow:mcp
Optional scope	offline_access for background renewal

Configure the endpoint and let your MCP client handle OAuth discovery and browser sign-in. Fellow uses public clients with Client ID Metadata Documents (CIMD). No client secret or API key is needed. Enter your password only on Fellow’s sign-in page, never in a prompt.

If implementing a client: follow the metadata URL in the unauthenticated 401 response’s WWW-Authenticate header, complete PKCE, then send the access token as a bearer token. Initialize MCP and call tools/list. Store tokens securely and use refresh tokens only when offline_access was granted. Account access is checked on every request, independently of token expiry.

Data and filters

• Apps. Omit appleAppIds to use active tracked apps, or supply Apple IDs for comparisons. Comparisons read existing Fellow data; they do not use tracked-app slots, start collection, or save a competitor list.
• Features. An App Store appearance has a type: story, room, section, app, or event. Events use their own Apple event ID and one parent app. Each activity interval represents one continuous appearance in one country. Reappearances stay separate.
• Countries. Use uppercase ISO-2 codes, such as US and GB. Omit the country filter for all countries.
• Dates. Use inclusive UTC dates in YYYY-MM-DD format. startDate defaults to the beginning of the account’s available history; endDate defaults to today. Future dates and reversed ranges are invalid.
• History. Requests outside the plan’s history return HISTORY_LIMIT. See Plans & Billing.

Date filters select overlapping appearances. Returned intervals can extend outside the requested range, but not before the plan’s history boundary. startedBeforeAvailableHistory marks a clipped start. Intersect dates with the returned window when calculating active days.

Apple IDs are strings. Fellow record IDs are integers. For unique features, group by app Apple ID, Apple feature ID, and feature type; add country when counting country placements. A Fellow record ID alone does not identify a feature across all appearances.

feature.tabs aggregates tabs observed across all countries and dates in that Fellow record. Country and date filters do not narrow it, even inside an activity interval. Do not use it to claim a tab for a specific country or date. An empty array means no tab metadata is recorded.

MCP does not return structured placement or recognition metadata, such as carousel positions, App of the Day or Editors’ Choice. Empty tabs or missing metadata do not prove absence of a placement or recognition.

Event appStoreUrl values link to https://apps.apple.com/<country>/app/id<appleAppId>?eventid=<appleFeatureId>. Event screenshots show the tab card.

Tools

All four tools are read-only. tools/list returns their current input and output JSON Schemas.

Tool	Purpose
fellow.list_apps	List active and paused tracked apps, metadata, and Apple links.
fellow.get_feature_activity	Get feature intervals across apps, countries, types, and dates.
fellow.get_feature	Get one feature record, country ranges, source links, and screenshot references.
fellow.get_screenshot	Retrieve one screenshot as MCP image content.

List apps

fellow.list_apps accepts only the pagination parameters. Returns apps, pagination, and an optional warning. Resolve app IDs here before requesting data. Paused apps appear in this list but are not included in the default activity query.

Get feature activity

fellow.get_feature_activity accepts pagination plus these optional filters:

Parameter	Type	Meaning
appleAppIds	string[]	Apps to compare. Omit for active tracked apps.
countryCodes	string[]	Countries. Omit for all countries.
featureTypes	string[]	story, room, section, app, event. Omit for all types.
startDate, endDate	string	Inclusive date range.

Returns window, apps, intervals, unavailableAppIds, and pagination. Each interval includes the app, feature, country, dates, and App Store URL. Unavailable apps are listed separately; they do not prevent available apps from being returned. Missing data is not zero activity.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fellow.get_feature_activity",
    "arguments": {
      "appleAppIds": ["570060128", "829587759"],
      "countryCodes": ["US", "GB"],
      "startDate": "2026-08-01",
      "endDate": "2026-08-31",
      "page": 1,
      "pageSize": 50
    }
  }
}

Get a feature

fellow.get_feature accepts pagination and these parameters:

Parameter	Type	Meaning
featureId	integer	Required. Fellow feature ID from an activity interval.
countryCode	string	Optional country filter.
startDate, endDate	string	Optional date range.

Returns window, feature, screenshots, and pagination. Summary dates describe that record’s available history; country ranges and screenshot references match the requested filters.

Get a screenshot

fellow.get_screenshot accepts:

Parameter	Type	Meaning
screenshotId	integer	Required. Screenshot reference id from get_feature.
appleAppId	string	Required. App ID from the same reference.
startDate, endDate	string	Pass the reference’s firstSeenDate and lastSeenDate.

Returns a base64-encoded WebP MCP image block and structuredContent.screenshot with dates, country, location, dimensions, MIME type, and byte length. Hosts with MCP Apps support can also show the screenshot viewer. Rendering and report embedding depend on the client.

Screenshots capture historical features. App Store links point to live pages, which may have changed.

Pagination

list_apps, get_feature_activity, and get_feature accept:

Parameter	Type	Default
page	integer	1
pageSize	integer	50

Results include pagination: { page, pageSize, hasMore }. Increment page while hasMore is true, keeping all other parameters unchanged. Finish pagination before calculating totals. Use the live schemas from tools/list for current request bounds.

Responses and errors

Successful results contain JSON text in content and the same data in structuredContent. Read the structured data for calculations. Screenshot results also include image content.

Tool failures return isError: true and structuredContent.error:

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "startDate must use YYYY-MM-DD."
  }
}

Code	Meaning
INVALID_INPUT	Invalid parameters or dates.
APP_DATA_UNAVAILABLE	App data is unavailable, or the request failed.
HISTORY_LIMIT	Requested data or dates exceed the plan’s history.
PLAN_REQUIRED	The account needs MCP access.
ACCESS_DENIED	MCP access is disabled for this account.
RATE_LIMITED	Retry after retryAfterSeconds, or narrow a timed-out request.
NOT_FOUND	Feature or screenshot not found.

Missing or invalid authentication returns HTTP 401. Malformed MCP requests and unknown tools return standard JSON-RPC errors. APP_SOFT_LIMIT is a warning on app listings, not a failed read; its message explains how to contact support.

Reports

The MCP prompt create_app_intelligence_report supplies optional report instructions through prompts/get. It accepts appleAppIds, countries, featureTypes (comma-separated strings), startDate, endDate, and layout (strings).

Without filters, the prompt suggests active tracked apps, the last 30 days, all countries, and all feature types. This report default differs from the tools’ full-history default. Clients create and store the report; Fellow does not generate reports or charts.

Requested Fellow data is sent to your AI provider. Fellow does not store conversations or generated reports. Usage limits and anti-abuse measures may apply.

Privacy Policy

·

Terms