Документация MCP-сервера

Обзор

MCP-сервер MaxList даёт ИИ-ассистентам доступ к каталогу maxlist.net только на чтение: поиск ресурсов, карточки, категории и топы. Он работает по протоколу Model Context Protocol в варианте Streamable HTTP и не хранит сессий.

Адрес	`https://api.maxlist.net/mcp`
Транспорт	Streamable HTTP, ответы JSON (POST)
Авторизация	`Authorization: Bearer mxl_…`
Версии протокола	2025-06-18, 2025-03-26, 2024-11-05

Быстрый старт

Зарегистрируйтесь на maxlist.net по почте или через Telegram.
В кабинете нажмите «Создать ключ» и скопируйте его: полностью ключ показывается один раз.
Добавьте сервер в клиент (ниже — Claude Code) и спросите ассистента о каналах.

Терминал

claude mcp add --transport http maxlist https://api.maxlist.net/mcp \
  --header "Authorization: Bearer mxl_ВАШ_КЛЮЧ"

Авторизация

Каждый запрос передаёт ключ в заголовке Authorization: Bearer mxl_…. Без ключа или с удалённым ключом сервер отвечает 401.

На аккаунт — до трёх ключей. Ключ можно удалить в кабинете, подключения с ним сразу перестанут работать.
В базе хранится только хеш ключа: если ключ потерян, создайте новый.
Не публикуйте ключ в открытых репозиториях — используйте переменные окружения.

Подключение клиентов

Claude Code

claude mcp add --transport http maxlist https://api.maxlist.net/mcp \
  --header "Authorization: Bearer mxl_ВАШ_КЛЮЧ"

Cursor

Файл ~/.cursor/mcp.json (или .cursor/mcp.json в проекте):

{
  "mcpServers": {
    "maxlist": {
      "url": "https://api.maxlist.net/mcp",
      "headers": {
        "Authorization": "Bearer mxl_ВАШ_КЛЮЧ"
      }
    }
  }
}

VS Code

Файл .vscode/mcp.json:

{
  "servers": {
    "maxlist": {
      "type": "http",
      "url": "https://api.maxlist.net/mcp",
      "headers": {
        "Authorization": "Bearer mxl_ВАШ_КЛЮЧ"
      }
    }
  }
}

Claude Desktop

Claude Desktop подключает удалённые серверы с заголовками через мост mcp-remote (нужен Node.js). Файл claude_desktop_config.json:

{
  "mcpServers": {
    "maxlist": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.maxlist.net/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer mxl_ВАШ_КЛЮЧ"
      }
    }
  }
}

Запрос вручную

Сервер принимает обычные JSON-RPC 2.0 запросы методом POST — удобно для проверки ключа и отладки.

Список инструментов

curl -s https://api.maxlist.net/mcp \
  -H "Authorization: Bearer mxl_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Вызов инструмента

curl -s https://api.maxlist.net/mcp \
  -H "Authorization: Bearer mxl_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_resources","arguments":{"query":"новости","limit":3}}}'

search_resources

Поиск по названию, юзернейму и короткому описанию. Результаты отсортированы по числу подписчиков. Ресурсы 18+ не возвращаются.

Параметр	Тип	Описание
`query`	string	Слова для поиска; совпасть должны все слова (до 5)
`type`	string	channel, group, bot или sticker
`category`	string	Слаг категории из list_categories
`min_subscribers`	integer	Минимальное число подписчиков
`limit`	integer	Результатов на странице: 1–10, по умолчанию 10
`page`	integer	Страница: 1–5

Ответ (structuredContent)

{
  "results": [
    {
      "username": "example_channel",
      "title": "Новости дня",
      "type": "channel",
      "category": "Образование",
      "subscribers": 48210,
      "description": "Короткое описание канала, не длиннее 160 символов…",
      "url": "https://maxlist.net/view/example_channel"
    }
  ],
  "page": 1,
  "has_more": true,
  "note": "Показаны основные поля. Посты, история подписчиков и аналитика — на странице ресурса (maxlist.net)."
}

get_resource

Карточка ресурса по юзернейму. Принимает юзернейм с @, без него или ссылку t.me.

Параметр	Тип	Описание
`username`	string, обязательный	Юзернейм ресурса

Ответ

{
  "found": true,
  "username": "example_channel",
  "title": "Новости дня",
  "type": "channel",
  "category": "Образование",
  "subscribers": 48210,
  "description": "Описание до 300 символов…",
  "url": "https://maxlist.net/view/example_channel",
  "verified": false,
  "rating": 12,
  "note": "Полная статистика (динамика подписчиков, читаемость, посты) — по ссылке url."
}

Если ресурса нет в каталоге: {"found": false, "username": "…"}.

Категории каталога со слагами и числом ресурсов. Параметров нет.

{
  "categories": [
    {
      "slug": "news-media",
      "name": "Новости и СМИ",
      "resources": 8682
    },
    {
      "slug": "education",
      "name": "Образование",
      "resources": 2950
    }
  ]
}

get_top

Десять крупнейших ресурсов по подписчикам — во всём каталоге или в категории.

Параметр	Тип	Описание
`type`	string	channel (по умолчанию), group, bot или sticker
`category`	string	Слаг категории из list_categories

Лимиты

Вызовов инструментов в сутки	300 на ключ (initialize и tools/list не считаются), сброс в полночь по Москве
Запросов в минуту	60 на ключ
Результатов за вызов	до 10, поиск — не дальше 5-й страницы
Ключей на аккаунт	3

Посты, история подписчиков и аналитика через MCP не отдаются — они доступны на странице ресурса по ссылке url.

Ошибки

Ответ	Что значит
HTTP 401, код -32001	Нет ключа, ключ неверный или удалён
HTTP 429	Больше 60 запросов в минуту — подождите
isError: true в результате	Инструмент не выполнен: неверный параметр или исчерпан дневной лимит (текст причины — в content)
код -32601	Метод не поддерживается
код -32602	Неизвестный инструмент
HTTP 405 на GET	Сервер без SSE-потока: используйте POST

Вопросы и пожелания — в поддержку. Описание публичного REST API — на странице API.