Подключить MCP-сервер к AI-агенту полезно, когда агенту нужны не только ответы модели, но и управляемые инструменты: веб-поиск, чтение страниц, исследования, RAG и фоновые задания. В LLMTOKENAPI удалённая точка подключения одна — https://api.llmtokenapi.ru/mcp; доступ выдаётся API-ключом с ограниченными scopes или через OAuth 2.1.
Когда Remote MCP лучше прямых REST-вызовов
REST подходит, если приложение само жёстко задаёт последовательность запросов. MCP удобнее для агентного клиента: он получает список доступных инструментов, их входные схемы и сам выбирает нужный вызов в рамках поставленной задачи. Один и тот же сервер можно подключить к coding agent, редактору или внутреннему ассистенту без отдельной обвязки для каждого метода.
Это не делает агента бесконтрольным. MCP лишь стандартизирует описание и вызов инструментов. Ограничения по ключу, бюджету, размеру запроса, публичности URL и доступу к данным продолжают действовать на стороне API. Общая модель протокола описана в официальной спецификации Model Context Protocol.
Подготовьте ключ с минимальными scopes
Для первого подключения не выдавайте ключ со всеми правами. Состав scopes зависит от задачи:
search:read— веб-поиск и ответ с цитатами;web:read— извлечение и чтение публичных URL;jobs:readиjobs:write— map, crawl и управление заданиями;research:readиresearch:write— исследования и Agent runs;knowledge:read— поиск по существующей базе знаний;rerank:read— смысловая пересортировка документов.
Создайте отдельный ключ для конкретного агента. Так его можно отозвать независимо от backend-приложения, а журнал использования будет проще разбирать. Секрет передавайте только в заголовке Authorization; не добавляйте его в URL, prompt, имя сервера или репозиторий.
Добавьте MCP-сервер в конфигурацию клиента
У разных клиентов расположение файла и имя поля отличаются, но логическая конфигурация одинакова. Укажите HTTPS-адрес /mcp и Bearer-заголовок через переменную окружения:
{
"mcpServers": {
"llmtokenapi": {
"url": "https://api.llmtokenapi.ru/mcp",
"headers": {
"Authorization": "Bearer ${LLMTOKENAPI_API_KEY}"
}
}
}
}
Не копируйте пример вслепую в публичный клиентский код: переменная должна подставляться локальным процессом или менеджером секретов. Если приложение не умеет раскрывать переменные в JSON, используйте его штатное защищённое хранилище. Адрес заканчивается на /mcp, а не на /v1/mcp.
Выберите API-ключ или OAuth
API-ключ — самый прямой вариант для серверного процесса, CI и личного агента на доверенном устройстве. Он заранее связан с организацией и scopes. Для пользовательского приложения, где разные люди подключают свои рабочие области, предпочтительнее OAuth 2.1 с PKCE: пользователь проходит авторизацию, а клиент не просит вручную вставлять постоянный секрет.
Remote MCP публикует метаданные защищённого ресурса и поддерживает OAuth-доступ, связанный с организацией. Клиент должен корректно проверять issuer и audience и выполнять поддерживаемый flow. Не пытайтесь имитировать OAuth, передавая токен в query string. Если конкретный клиент пока не поддерживает discovery или PKCE, используйте отдельный короткоживущий по процессу API-ключ и ограничьте его права.
Проверьте инструменты до рабочей задачи
После подключения попросите клиент показать доступные tools. Набор зависит от scopes. Для минимального поискового ключа ожидаемы web_search и web_answer; для web:read добавляются web_extract, web_contents, web_fetch и web_scrape. Права на исследования открывают инструменты запуска и чтения Agent run, а knowledge:read — поиск по базе знаний.
Выполните безопасную проверку без чувствительных данных: попросите найти официальную страницу и вернуть заголовок с URL. Затем убедитесь, что ответ инструмента содержит структурированный результат, а не только свободный текст. Актуальные REST-маршруты, на которые опираются tools, доступны в OpenAPI LLMTOKENAPI.
Учитывайте фоновые операции и идемпотентность
Map, crawl, research и Agent run выполняются асинхронно. MCP-инструмент запуска возвращает handle задания, а завершение читается отдельным вызовом. Не просите модель бесконечно повторять создание, если результат не появился мгновенно: сначала сохраните идентификатор и проверяйте статус.
Для операций создания сервер формирует отдельный Idempotency-Key. Это защищает конкретный сетевой повтор от второго задания и резервирования. Однако новый самостоятельный tool call является новым логическим запуском. В системной инструкции агента явно задайте правило: после успешного старта работать с полученным id, а повторно запускать задачу только по решению пользователя.
Подробная клиентская логика ожидания разобрана в статье про Research API и события.
Ограничьте агентную свободу правилами задачи
Передавайте агенту точную цель, допустимые домены, форму результата и критерий остановки. Если задача допускает дорогой многошаговый запуск, задайте maxSpendKopecks и разумный maxSources. Для чтения внутренних документов подключайте только нужную базу знаний; не смешивайте корпоративные данные с публичным веб-поиском без явной причины.
Результаты веб-инструментов являются недоверенными данными. Страница может содержать инструкции для модели, но они не должны менять системные правила, scopes или адрес назначения. Перед внешним действием проверяйте URL и содержимое отдельно. LLMTOKENAPI блокирует приватные и служебные адреса, но бизнес-ограничения всё равно остаются ответственностью вашего приложения.
Соберите короткий production-чеклист
Перед постоянным использованием проверьте пять вещей: отдельный ключ с минимальными scopes, отсутствие секрета в файлах и логах, видимость только ожидаемых tools, корректную обработку ошибок и сохранение handle фоновой операции. Добавьте таймауты и предел числа вызовов на одну пользовательскую задачу.
Полная документация LLMTOKENAPI содержит правила авторизации, scopes и схемы методов. Надёжное подключение MCP-сервера к AI-агенту начинается не с большого набора инструментов, а с одного проверяемого сценария и минимального доступа. После успешного smoke-теста расширяйте scopes по одному и измеряйте, какие tools действительно приносят пользу.
