MCP-сервер

MCP-сервер Lovely Router позволяет агенту самостоятельно спланировать задачу, найти инструмент, прочитать его схему входных данных, запустить его и прочитать результаты. Через него также доступен браузерный агент. Каждый вызов проходит через тот же API, что и REST, поэтому оплата, ограничения и ошибки полностью совпадают.

Подключение клиента#

Сначала создайте ключ в разделе API-ключи. Для агентов разумно использовать ключ с лимитом расходов: см. контроль расходов.

claude mcp add --transport http lovely-tools https://lovelyrouter.com/mcp \
  --header "Authorization: Bearer $LOVELY_API_KEY"

{
  "mcpServers": {
    "lovely-tools": {
      "type": "http",
      "url": "https://lovelyrouter.com/mcp",
      "headers": { "Authorization": "Bearer ${LOVELY_API_KEY}" }
    }
  }
}

Проверка подключения#

Сервер работает по обычному JSON-RPC, поэтому его можно вызвать через cURL. Этот запрос выводит список доступных инструментов:

curl https://lovelyrouter.com/mcp \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Инструменты сервера#

Два инструмента ищут и читают веб-страницы. Сервер подсказывает агенту использовать их для всего, что нужно найти или прочитать, а браузерного агента оставлять для страниц, с которыми нужно взаимодействовать.

Два инструмента создают изображения с помощью GPT Image 2.5 (или GPT Image 2, если 2.5 недоступна) и оплачиваются как Images API: $0.04 за изображение любого размера, при неудаче — ничего.

Пять инструментов работают с каталогом данных. Сервер подсказывает агенту планировать через suggest_tools (или search_tools, если нужен один инструмент), читать схему через get_tool, а затем вызывать run_tool.

Четыре инструмента управляют браузерным агентом. Он нужен для страниц, с которыми агенту приходится взаимодействовать: вход в аккаунт, формы, многошаговые сценарии. Чтобы просто прочитать содержимое страницы, web_fetch быстрее и дешевле. Браузер работает в облаке и не может открывать localhost или частные адреса.

Каждый аргумент браузера описан в руководствах по браузерному агенту: режимы, структурированный вывод, вход в аккаунты и профили, файлы и участие человека. Пароли и одноразовые коды не передаются через MCP: агент обращается к секретам из хранилища по имени, а коды человек отправляет через API.

Что возвращают инструменты#

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

• web_search возвращает пронумерованные результаты с заголовком, сайтом, датой, URL и кратким содержанием. web_fetch возвращает страницу частями примерно по 12 000 символов вместе с run_id и offset для чтения продолжения.
• run_tool и get_run возвращают строку с идентификатором запуска, инструментом, статусом, числом результатов и списанной суммой, а затем по строке на каждый результат — без пустых полей и с обрезанным длинным текстом. В один ответ помещается около 12 000 символов, а последняя строка подсказывает, как получить остальное: get_run с offset или fields, чтобы оставить только нужные ключи. Полный JSON по-прежнему доступен через GET /v1/tools/runs/{run_id}.
• Остальные инструменты возвращают в виде текста тот же JSON, что и соответствующий REST-эндпоинт: POST /v1/tools/suggest, POST /v1/tools/discover и GET /v1/tools/{id}.
• Ошибки возвращаются как результат инструмента с isError: true и сообщением, чтобы агент мог скорректировать действия. Если run_tool отклоняет входные данные, в ответе перечислены входные поля инструмента и приведён пример.
• generate_image и get_image возвращают строку с идентификатором задания, размером изображения, размером файла и списанной суммой, ссылку для скачивания и команду curl для неё. Это такое же задание, как созданное через POST /v1/images/jobs, поэтому оно видно в логах, а изображение 7 дней доступно по GET /v1/images/jobs/{id}/content с вашим ключом.
• Долгие запуски. run_tool ждёт до 50 секунд, потому что большинство клиентов прерывают вызов инструмента примерно через минуту. Запуск, который всё ещё идёт после этого, возвращается как Still running. Call get_run with this run id to get the results. вместе с данными запуска. Клиент, допускающий более долгие вызовы инструментов, может добавить ?wait= к URL сервера (от 10 до 280 секунд).

Без ключа#

suggest_tools, search_tools и get_tool работают без ключа, поэтому агент может просматривать каталог ещё до того, как вы подключите ключ. run_tool, get_run и инструменты браузера возвращают ошибку аутентификации, пока ключ не добавлен.

Как выглядит сессия агента#

Подключите сервер и попросите Claude Code: «Найди веганские рестораны в Остине и расскажи, на что жалуются в отзывах о них». Типичная сессия:

1. План. Агент вызывает suggest_tools с задачей. План предлагает сначала запустить google-maps-places, затем google-maps-reviews, с оценкой $0.0585 при лимитах по умолчанию.
2. Чтение схемы. Агент вызывает get_tool с {"tool": "google-maps-places"}, чтобы увидеть входные поля.
3. Поиск мест. Агент вызывает run_tool:
   JSON

   {
     "tool": "google-maps-places",
     "input": {"searchTerms": ["vegan restaurant"], "location": "Austin, Texas, USA"},
     "max_results": 10
   }

   Возвращаются десять мест с их placeId. Стоимость: $0.00075 + 10 × $0.000238 = $0.00313.

4. Получение отзывов. Агент снова вызывает run_tool с идентификаторами мест, по пять отзывов на место:
   JSON

   {
     "tool": "google-maps-reviews",
     "input": {"placeIds": ["ChIJ...", "ChIJ..."], "maxReviews": 5, "reviewsSort": "newest"},
     "max_results": 50
   }

   Возвращаются пятьдесят отзывов. Стоимость: 50 × $0.000675 = $0.03375.

5. Ответ. Агент читает отзывы и обобщает жалобы. Вся задача стоила около $0.08, а оба запуска видны в разделе Инструменты панели управления.

Цены выше — текущие. get_tool и suggest_tools всегда возвращают актуальную цену.

Контроль расходов#

• Выдайте агенту отдельный ключ с лимитом расходов. Запуск, который может превысить лимит ключа, отклоняется с кодом 402 до какого-либо списания. См. API-ключи.
• Требуйте max_results в каждом запуске. Лимит ограничивает стоимость: плата за вызов плюс плата за результат, умноженная на max_results. Без него применяется значение инструмента по умолчанию. Достаточно строки в промпте или инструкциях проекта: «Всегда задавай max_results и спрашивай меня перед любым запуском, который может стоить больше $0.50».
• Сначала планируйте. suggest_tools и get_tool бесплатны и показывают цену, так что агент может проверить максимальную стоимость запуска до его начала.
• Проверяйте расходы. Каждый запуск и списание по нему перечислены в разделе Инструменты. Неудачные запуски без результатов ничего не стоят.

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