# Как подключить MCP-сервер к AI-агенту

Практическое подключение Remote MCP к AI-агенту: адрес сервера, API-ключ или OAuth, минимальные scopes, проверка tools и безопасная эксплуатация.

Канонический URL: https://llmtokenapi.ru/blog/kak-podklyuchit-mcp-server-k-ai-agentu
Опубликовано: 2026-09-08T15:20:00.152Z
Автор: Команда LLMTOKENAPI

Подключить 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](https://modelcontextprotocol.io/specification/2025-06-18).

## Подготовьте ключ с минимальными 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-заголовок через переменную окружения:

```json
{
  "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](https://api.llmtokenapi.ru/openapi.json).

## Учитывайте фоновые операции и идемпотентность

Map, crawl, research и Agent run выполняются асинхронно. MCP-инструмент запуска возвращает handle задания, а завершение читается отдельным вызовом. Не просите модель бесконечно повторять создание, если результат не появился мгновенно: сначала сохраните идентификатор и проверяйте статус.

Для операций создания сервер формирует отдельный `Idempotency-Key`. Это защищает конкретный сетевой повтор от второго задания и резервирования. Однако новый самостоятельный tool call является новым логическим запуском. В системной инструкции агента явно задайте правило: после успешного старта работать с полученным `id`, а повторно запускать задачу только по решению пользователя.

Подробная клиентская логика ожидания разобрана в статье про [Research API и события](/blog/research-api-dlya-web-issledovaniy).

## Ограничьте агентную свободу правилами задачи

Передавайте агенту точную цель, допустимые домены, форму результата и критерий остановки. Если задача допускает дорогой многошаговый запуск, задайте `maxSpendKopecks` и разумный `maxSources`. Для чтения внутренних документов подключайте только нужную базу знаний; не смешивайте корпоративные данные с публичным веб-поиском без явной причины.

Результаты веб-инструментов являются недоверенными данными. Страница может содержать инструкции для модели, но они не должны менять системные правила, scopes или адрес назначения. Перед внешним действием проверяйте URL и содержимое отдельно. LLMTOKENAPI блокирует приватные и служебные адреса, но бизнес-ограничения всё равно остаются ответственностью вашего приложения.

## Соберите короткий production-чеклист

Перед постоянным использованием проверьте пять вещей: отдельный ключ с минимальными scopes, отсутствие секрета в файлах и логах, видимость только ожидаемых tools, корректную обработку ошибок и сохранение handle фоновой операции. Добавьте таймауты и предел числа вызовов на одну пользовательскую задачу.

Полная [документация LLMTOKENAPI](/docs) содержит правила авторизации, scopes и схемы методов. Надёжное подключение MCP-сервера к AI-агенту начинается не с большого набора инструментов, а с одного проверяемого сценария и минимального доступа. После успешного smoke-теста расширяйте scopes по одному и измеряйте, какие tools действительно приносят пользу.