MCP tool reference

This reference is for users configuring an MCP client or inspecting which Searcherries data their assistant retrieves. The server exposes two read-only tools: list-projects and get-project-data.

Connect to https://app.searcherries.com/mcp/searcherries using authorized OAuth or a personal access token. See connection options.

list-projects

Lists projects belonging to the authenticated account, their connected sources, and indicators of available stored data.

This tool takes no project-selection arguments. Call it first to obtain a project ID and confirm that the requested brand is available.

A returned project does not necessarily have data in every section. A new project may have no completed checks, and an unconnected analytics source cannot provide a performance snapshot.

get-project-data

Returns selected datasets for one project.

Argument	Required	Meaning
`project_id`	Yes	Positive integer ID obtained from `list-projects`.
`sections`	No	Array of dataset identifiers. Omit it to request all available sections.
`limit`	No	Rows or snapshots per paginated section, from 1 to 100. Default: 25.
`offset`	No	Rows to skip in each requested paginated section, from 0 to 100000. Default: 0.

Example tool arguments:

{
  "project_id": 123,
  "sections": [
    "ai_visibility.metrics",
    "competitors",
    "citations.urls"
  ],
  "limit": 25,
  "offset": 0
}

Replace 123 with an ID returned for your account. It is an illustrative value, not a shared demo project.

Dataset identifiers

Identifier	Contents
`ai_visibility.metrics`	Stored project visibility metrics.
`ai_visibility.topics`	Stored topic records, when the project has them.
`ai_visibility.prompts`	Customer questions and their tracking information.
`ai_visibility.mentions`	Collected AI response and mention records.
`citations.top_sites`	Stored leading-source or domain snapshots.
`citations.urls`	Individual recorded source URLs and associated metadata.
`competitors`	Stored competitor snapshots and platform metrics.
`recommendations`	Stored recommendation records, where available.
`trust_mentions`	Existing trust-platform mention records, where available.
`ga4.ai_traffic`	Stored GA4 AI-traffic snapshots.
`google_search_console.performance`	Stored Google search-performance snapshots.
`bing_webmaster_tools.performance`	Stored Bing search-performance snapshots.

Some identifiers preserve access to historical data. Their presence does not mean there is a current standalone page or ongoing collection for that dataset. Stored recommendation records are also not the same thing as your Wizard session history.

Pagination

Paginated sections return offset, limit, returned, total, and has_more. When has_more is true, request the next page with an increased offset. Requesting a single section makes pagination easier when different datasets have different lengths.

For analytics snapshots, the limit counts snapshots, not necessarily the individual query or page rows nested inside each snapshot. Inspect the response's dates and shape before combining results.

Freshness and errors

The response identifies the data as stored, read-only data. Check each dataset's update time and period rather than assuming all sections cover identical dates.

An authentication error calls for reconnection. A project-not-found error can mean an incorrect ID or a project unavailable to the authorized account. Unknown section names and out-of-range pagination values are rejected.

These tools do not refresh external services or alter projects. Read about data updates.