MCP Data API¶

Основная информация¶

MCP-сервер FraudScore позволяет языковым моделям (LLM) и MCP-совместимым клиентам получать аналитические данные о качестве трафика из FraudScore Data API. Клиент формулирует задачу («покажи топ веб-мастеров по фрод-скорингу за сентябрь»), LLM вызывает подходящий tool с корректными параметрами, сервер обращается к Data API и возвращает готовые данные.

Возможности:

• выгрузка инсталлов и custom-событий за период (построчно или агрегированно);
• группировки, фильтры, сортировка, пагинация;
• агрегированные срезы по связкам «инсталл ↔ custom-событие»;
• разумные значения по умолчанию — достаточно указать канал и период;
• список каналов аккаунта (list_channels) — рекомендованная точка входа;
• разграничение доступа: аккаунт видит только свои каналы;
• все tools помечены аннотацией read-only (клиенты типа Claude Desktop и Cursor отображают это в интерфейсе).

Подключение¶

Токен (mcp_*) выдаётся FraudScore и передаётся в заголовке Authorization с каждым запросом. По токену сервер определяет аккаунт и доступные ему каналы. Токен персональный — храните его как секрет.

Конфигурация для типичного MCP-клиента (Claude Desktop, Cursor и др.) — обратите внимание на "type": "http": без него клиент попытается запустить локальный stdio-процесс:

{
  "mcpServers": {
    "fraudscore-data-api": {
      "type": "http",
      "url": "[https://mcp-data.fraudscore.ru/mcp](https://mcp-data.fraudscore.ru/mcp)",
      "headers": {
        "Authorization": "Bearer mcp_ваш_токен"
      }
    }
  }
}

Пример клиента на Node.js:

import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'

const transport = new StreamableHTTPClientTransport(new URL('[https://mcp-data.fraudscore.ru/mcp](https://mcp-data.fraudscore.ru/mcp)'), {
  requestInit: { headers: { Authorization: `Bearer ${MCP_TOKEN}` } }
})
const client = new Client({ name: 'my-app', version: '1.0.0' })
await client.connect(transport)

const result = await client.callTool({
  name: 'get_installs',
  arguments: { channelId: 'my-channel', date_from: '2026-09-01', date_to: '2026-09-15' }
})

Или напрямую JSON-RPC поверх HTTP:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_installs",
    "arguments": { "channelId": "my-channel", "date_from": "2026-09-01", "date_to": '2026-09-15' }
  }
}

Инструменты¶

list_channels¶

Список идентификаторов каналов (channelId), доступных аккаунту. Параметров не принимает.

{ "channels": ["12345", "67890"] }

Рекомендуемая точка входа: сначала получите свои channelId, затем используйте их в инструментах данных (get_installs, get_custom_events, get_install_custom_groups, get_custom_install_groups).

Список каналов одинаков на любом эндпоинте. При этом отдельный канал может обслуживаться другим эндпоинтом: если инструмент данных вернул ошибку зоны, подключитесь к эндпоинту, указанному в тексте ошибки.

Общие параметры запросов

Таблица относится к инструментам данных; list_channels параметров не принимает.

get_installs¶

Данные по инсталлам за период. Без group — построчный список событий, с group — агрегированный срез (фрод-скоринг, количество, выплаты, стоимость). Для вопросов об инсталлах, фроде инсталлов и срезах по измерениям инсталлов.

get_custom_events¶

Данные по custom-событиям за период (in-app события вашего приложения: регистрация, покупка, достижение уровня и т.п.). Те же режимы; стандартный набор полей адаптирован под custom (добавлены name и value события). Дефолтные агрегаты custom: score_avg и count.

get_install_custom_groups¶

Инсталлы с разбивкой по custom-событиям: группы инсталлов по заданному ключу, каждая строка — количество инсталлов плюс разбивка по каждому custom-событию (массивы custom_count/custom_users, выровненные с заголовком events по индексу). Для вопросов вида «инсталлы по веб-мастерам с их custom-событиями». group обязателен; filters — по инсталлам, custom_filters — по custom-событиям. Не путать с get_custom_install_groups.

get_custom_install_groups¶

Custom-события с привязкой к инсталлам: группы custom-событий по заданному ключу со счётчиками, связанными с инсталлами (массивы custom_count/custom_users, выровненные с events по индексу). Для вопросов вида «custom-события по странам». group обязателен; дефолтные агрегаты — score_avg и count (агрегаты выплат метод не принимает). Ключ группировки присутствует в строках, но может быть пустым, если у custom-событий нет такого поля. Не путать с get_install_custom_groups.

list_available_fields¶

Справочник доступных полей: ключи, режимы (list/group), ключи группировки, доступность для фильтрации. Опциональный параметр mode: "list" | "group". Рекомендуется вызывать перед использованием незнакомых имён полей.

Значения по умолчанию¶

Если параметры не заданы, сервер применяет проверенные наборы:

• Поля списка: стандартный набор полей метода (для custom — свой, без инсталльных полей, с name и value).
• Поля группировки: score_avg, count, affiliate_payout_sum, cost_sum, score_ok/low/mid/high для инсталльных методов; для методов на базе custom — только score_avg и count (агрегаты выплат недоступны).
• Поле score добавляется в каждый запрос автоматически (в группировках — score_avg).
• Поле сортировки, отсутствующее в выборке, добавляется в fields автоматически (правило API: сортировка только по полям ответа).
• Сортировка: score_desc (в группировках score_avg_desc).
• Пагинация: весь результат без разбиения (page=all).

Псевдонимы полей: в режиме группировки offer_name → any_offer_name, affiliate_payout → affiliate_payout_sum и т.д. — можно передавать любое из имён. В параметр group всегда идут обычные ключи (offer_id), не any_*.

Формат ответа¶

Tool возвращает компактный JSON. Примеры ниже иллюстративны; состав событий и значения зависят от вашего приложения:

{"url":"[https://api.fraudscore.ru/{channel}/install?key=***&](https://api.fraudscore.ru/{channel}/install?key=***&)...","mode":"list","period":{"from":"2026-09-01","to":"2026-09-15"},"page":"all","events":null,"row_count":2,"truncated":false,"rows":[{"datetime":"2026-09-01T10:00:00","offer_id":"...","score":87}]}

Для агрегационных методов добавляется заголовок events (имена custom-событий), отделённый от строк данных:

{"url":"...","mode":"group","page":"all","events":["registration","first_purchase"],"row_count":54,"truncated":false,"rows":[{"affiliate_id":"123","count":"1050","score_avg":15,"custom_count":["600","350"],"custom_users":["590","340"]}]}

• url — сформированный запрос к Data API с замаскированным ключом (для прозрачности и отладки);
• events — заголовок агрегационных методов: имена custom-событий; массивы custom_count/custom_users в строках соответствуют им по индексу;
• rows — массив строк результата;
• truncated — true, если при постраничном режиме пришла полная страница; вместе с ним приходит next_page — номер следующей страницы.

Ошибки¶

Уровень HTTP (авторизация и тело запроса):

Уровень tool (JSON-RPC): при ошибке выполнения возвращается результат с isError: true и текстом причины на английском: доступ к каналу запрещён, интеграция недоступна в текущей зоне (с указанием подходящего эндпоинта), неизвестное поле (со списком допустимых значений), инвертированный период, ошибка Data API. LLM может использовать текст ошибки для самокоррекции запроса.

Ограничения¶

• Не более 60 запросов в минуту и не более одного запроса в секунду к Data API (сервер соблюдает лимит автоматически).
• Учётная запись имеет доступ только к своим каналам; обращение к чужому channelId отклоняется.
• Ответ при page=all не ограничен по размеру: для чат-сценариев (Claude Desktop, Cursor) учитывайте, что весь результат попадёт в контекст модели.
• Эндпоинт обслуживает интеграции только своей зоны: при обращении к интеграции другой зоны возвращается ошибка с указанием подходящего эндпоинта. Список каналов (list_channels) при этом всегда полный — независимо от эндпоинта.

Безопасность¶

• Токен — персональный секрет: передавайте его только в заголовке Authorization, храните в защищённом хранилище и перевыпускайте при подозрении на компрометацию.
• Все соединения выполняются по HTTPS.
• Учётная запись имеет доступ только к данным своих каналов.
• Сервер не хранит состояние между запросами.

7 окт 2026 г.