MCP Blacklist¶

Введение¶

Сервис управления блэклистом каналов FraudScore предоставляет единый интерфейс, который можно использовать двумя способами:

• как MCP-сервер — подключив его к любому LLM-клиенту с поддержкой Model Context Protocol (Claude Desktop, Cursor и др.);
• как обычный JSON-RPC 2.0 API — отправляя запросы напрямую из вашего кода, без участия LLM.

Это один и тот же протокол и один и тот же набор инструментов: MCP-транспорт построен поверх JSON-RPC 2.0, поэтому любой запрос, который отправляет MCP-клиент, вы можете воспроизвести обычным HTTP-вызовом POST /mcp.

Обратите внимание: имена инструментов, их описания и все тексты, возвращаемые API (сообщения об успехе и ошибки), всегда возвращаются на английском языке — независимо от языка документации. Это сделано для однозначной интерпретации как LLM, так и интеграциями.

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

Сервис не поддерживает сессии: каждый HTTP-запрос обрабатывается независимо. Вам не нужно хранить идентификатор сессии, выполнять рукопожатие или повторно инициализировать соединение — достаточно отправлять отдельные JSON-RPC-запросы.

Аутентификация¶

Все запросы к POST /mcp требуют токен API в заголовке Authorization:

Authorization: Bearer mcp_XXXXXXXXXXXXXXXX

Требования к токену:

• префикс mcp_;
• далее от 8 до 128 символов: латинские буквы, цифры, _, - и ..

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

Токен — это секрет. Передавайте его только по HTTPS и не публикуйте в открытых источниках.

Инструменты (tools)¶

Сервис предоставляет три инструмента. Описания инструментов (то, что видит LLM в tools/list) и их имена — на английском языке. Для инструментов чтения и записи объявлены стандартные аннотации MCP (readOnlyHint, destructiveHint, idempotentHint) — MCP-клиенты могут использовать их для подтверждения опасных действий.

list_channels¶

Возвращает список идентификаторов каналов, доступных вашему аккаунту. Параметров не имеет.

Результат: {"channels": ["my_channel_1", "my_channel_2"]} — только идентификаторы, без дополнительной информации о каналах.

Типичный порядок работы: сначала list_channels для получения доступных ID, затем get_install_filter / update_install_filter для чтения и изменения.

get_install_filter¶

Получает текущие настройки блэклиста канала.

Параметры:

Формат channelId: строка от 1 до 200 символов, допускаются латинские буквы, цифры, _ и -. Числовые идентификаторы также принимаются.

Результат: объект install_filter с текущей конфигурацией фильтра канала (см. формат ниже).

update_install_filter¶

Обновляет настройки блэклиста канала.

Параметры:

Важно: операция заменяет конфигурацию фильтра целиком — переданные списки не объединяются с существующими. Чтобы сохранить текущие значения, сначала получите их через get_install_filter, внесите изменения и отправьте полный объект.

Результат: подтверждение успешного обновления и применённая конфигурация фильтра.

Формат install_filter¶

{
  "type": "block",
  "affiliate": ["affiliate_1", "affiliate_2"],
  "offer": ["offer_1"]
}

Ограничения списков affiliate и offer:

• максимум 100 элементов в каждом списке;
• каждый элемент — строка от 1 до 648 символов (пробелы по краям обрезаются);
• отсутствие поля в запросе или передача пустого массива [] очищает список;
• все поля, кроме перечисленных выше, запрещены — объект валидируется строго, лишние поля приводят к ошибке.

Поле type обязательно в каждом запросе на обновление, включая те случаи, когда вы меняете только списки.

Прямой API¶

Любой инструмент вызывается методом JSON-RPC tools/call. Для получения списка доступных инструментов используйте tools/list.

Заголовки запроса¶

POST https://mcp.fraudscore.ru/mcp
Authorization: Bearer mcp_XXXXXXXXXXXXXXXX
Content-Type: application/json
Accept: application/json, text/event-stream

Получение списка инструментов¶

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Вызов list_channels¶

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list_channels",
    "arguments": {}
  }
}

Пример ответа:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"channels\":[\"my_channel_1\",\"my_channel_2\"]}"
      }
    ],
    "isError": false
  }
}

Вызов get_install_filter¶

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_install_filter",
    "arguments": {
      "channelId": "my_channel_1"
    }
  }
}

Пример ответа:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"install_filter\":{\"type\":\"block\",\"affiliate\":[\"affiliate_1\"]}}"
      }
    ],
    "isError": false
  }
}

Полезная нагрузка инструмента всегда возвращается в result.content[0].text в виде компактной JSON-строки (без пробелов и переносов) — распарсите её на своей стороне (например, JSON.parse в JavaScript).

Вызов update_install_filter¶

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "update_install_filter",
    "arguments": {
      "channelId": "my_channel_1",
      "install_filter": {
        "type": "block",
        "affiliate": ["affiliate_1", "affiliate_2"],
        "offer": ["offer_1"]
      }
    }
  }
}

Пример успешного ответа:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"success\":true,\"message\":\"Filter updated successfully\",\"install_filter\":{\"type\":\"block\",\"affiliate\":[\"affiliate_1\",\"affiliate_2\"],\"offer\":[\"offer_1\"]}}"
      }
    ],
    "isError": false
  }
}

Пример на JavaScript (без SDK)¶

const response = await fetch('https://mcp.fraudscore.ru/mcp', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer mcp_XXXXXXXXXXXXXXXX',
    'Content-Type': 'application/json',
    'Accept': 'application/json, text/event-stream'
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/call',
    params: {
      name: 'get_install_filter',
      arguments: { channelId: 'my_channel_1' }
    }
  })
})

const rpc = await response.json()
const payload = JSON.parse(rpc.result.content[0].text)
console.log(payload.install_filter)

MCP-сервер¶

Подключите сервис к вашему MCP-клиенту. Пример конфигурации:

{
  "mcpServers": {
    "fraudscore": {
      "type": "http",
      "url": "https://mcp.fraudscore.ru/mcp",
      "headers": {
        "Authorization": "Bearer mcp_XXXXXXXXXXXXXXXX"
      }
    }
  }
}

После подключения вы сможете давать модели инструкции на естественном языке, например:

• «Покажи доступные каналы»;
• «Покажи текущий блэклист канала my_channel_1»;
• «Добавь аффилиата affiliate_3 в блэклист канала my_channel_1» — при таком запросе модель сама выполнит цепочку: list_channels → get_install_filter → update_install_filter с полным объектом.

Клиент и сервер обмениваются теми же JSON-RPC-сообщениями, что и при прямых вызовах, — просто за их формирование отвечает MCP-клиент и LLM. Общаться с моделью можно на любом языке; на английском возвращаются только служебные тексты API (описания инструментов, сообщения об успехе и ошибках).

Обработка ошибок¶

Ошибки возвращаются на двух уровнях. Все тексты ошибок API — на английском языке.

HTTP-уровень¶

Уровень инструмента¶

Если HTTP-запрос прошёл, но сам инструмент не смог выполнить операцию, ответ приходит с isError: true и текстовым описанием ошибки на английском.

Пример — отсутствие доступа к каналу:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Access to channel my_channel_2 denied"
      }
    ],
    "isError": true
  }
}

Пример — ошибка валидации фильтра (в ответе указывается конкретная причина):

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Invalid install_filter: \"type\" must be strictly \"block\""
      }
    ],
    "isError": true
  }
}

Типичные причины и форматы сообщений:

• нет доступа к каналу — канал не привязан к аккаунту вашего токена: Access to channel ... denied;
• ошибка валидации install_filter — лишние поля, неверный type, слишком длинные значения и т.д.: Invalid install_filter: <конкретная причина>;
• внутренний сбой — нейтральное сообщение без раскрытия деталей: Failed to retrieve filter при чтении, Failed to update filter при записи.

Такой формат сообщений позволяет интеграции (и LLM) сразу понять причину ошибки и исправить запрос, не раскрывая внутренние детали работы сервиса.

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

• Один запрос — одна операция: сервис не хранит состояние между запросами.
• Операция обновления заменяет конфигурацию фильтра целиком: чтобы сохранить текущие списки, сначала получите их через get_install_filter, внесите изменения и отправьте полный объект.
• Повторная отправка одного и того же запроса на обновление безопасна: она приводит фильтр к одному и тому же состоянию.
• Все запросы и ответы используют кодировку UTF-8.

7 окт 2026 г.