trustgraph/docs/tech-specs/mcp-tool-bearer-token.ru.md

layout	title	parent
default	Спецификация аутентификации токенов Bearer для инструментов MCP	Russian (Beta)

Спецификация аутентификации токенов Bearer для инструментов MCP

Beta Translation: This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

⚠️ ВАЖНО: ТОЛЬКО ДЛЯ ОДНОГО АРЕНДАТОРА

Эта спецификация описывает базовый механизм аутентификации на уровне сервиса для инструментов MCP. Это НЕ полное решение для аутентификации и НЕ подходит для:

• Многопользовательских сред
• Многоарендных развертываний
• Федеративной аутентификации
• Распространения контекста пользователя
• Авторизации на уровне пользователя

Эта функция предоставляет один статический токен для каждого инструмента MCP, который используется всеми пользователями и сеансами. Если вам требуется аутентификация на уровне пользователя или арендатора, это не подходящее решение.

Обзор

Название функции: Поддержка аутентификации токенов Bearer для инструментов MCP Автор: Claude Code Assistant Дата: 2025-11-11 Статус: В разработке

Краткое описание

Позволяет конфигурациям инструментов MCP указывать необязательные токены Bearer для аутентификации с защищенными серверами MCP. Это позволяет TrustGraph безопасно вызывать инструменты MCP, размещенные на серверах, требующих аутентификации, без изменения интерфейсов агента или вызова инструментов.

ВАЖНО: Это базовый механизм аутентификации, предназначенный для сценариев аутентификации от сервиса к сервису в одноарендной среде. Он НЕ подходит для: Многопользовательских сред, где разные пользователи нуждаются в разных учетных данных Многоарендных развертываний, требующих изоляции на уровне арендатора Сценариев федеративной аутентификации Аутентификации или авторизации на уровне пользователя Динамического управления учетными данными или обновления токенов

Эта функция предоставляет статический, системный токен Bearer для каждой конфигурации инструмента MCP, который используется всеми пользователями и вызовами этого инструмента.

Описание проблемы

В настоящее время инструменты MCP могут подключаться только к общедоступным серверам MCP. Многие производственные развертывания MCP требуют аутентификации с помощью токенов Bearer для обеспечения безопасности. Без поддержки аутентификации: Инструменты MCP не могут подключаться к защищенным серверам MCP Пользователям приходится либо предоставлять доступ к серверам MCP в общедоступном режиме, либо использовать обратные прокси Нет стандартизированного способа передачи учетных данных для подключений MCP Невозможно применять лучшие практики безопасности к конечным точкам MCP

Цели

[ ] Разрешить конфигурациям инструментов MCP указывать необязательный параметр auth-token [ ] Обновить сервис инструмента MCP для использования токенов Bearer при подключении к серверам MCP [ ] Обновить инструменты командной строки для поддержки установки/отображения токенов аутентификации [ ] Сохранить обратную совместимость с конфигурациями MCP без аутентификации [ ] Задокументировать соображения безопасности для хранения токенов

Не включено

Динамическое обновление токенов или потоки OAuth (только статические токены) Шифрование хранимых токенов (безопасность системы конфигураций не входит в область) Альтернативные методы аутентификации (базовая аутентификация, ключи API и т. д.) Проверка срока действия или истечения срока действия токенов Аутентификация на уровне пользователя: Эта функция НЕ поддерживает учетные данные, специфичные для пользователя Изоляция на уровне арендатора: Эта функция НЕ предоставляет управление токенами на уровне арендатора Федеративная аутентификация: Эта функция НЕ интегрируется с поставщиками идентификации (SSO, OAuth, SAML и т. д.) Аутентификация, зависящая от контекста: Токены не передаются на основе контекста пользователя или сеанса

Предыстория и контекст

Текущее состояние

Конфигурации инструментов MCP хранятся в группе конфигураций mcp со следующей структурой:

{
  "remote-name": "tool_name",
  "url": "http://mcp-server:3000/api"
}

Сервис инструмента MCP подключается к серверам, используя streamablehttp_client(url), без каких-либо заголовков аутентификации.

Ограничения

Текущие ограничения системы:

1. Отсутствие поддержки аутентификации: Невозможно подключиться к защищенным серверам MCP.
2. Риски безопасности: Серверы MCP должны быть общедоступными или использовать только сетевую безопасность.
3. Проблемы при развертывании в производственной среде: Невозможно соблюдать лучшие практики безопасности для API-интерфейсов.

Ограничения данного решения:

1. Только для однопользовательской системы: Один статический токен для каждого инструмента MCP, общий для всех пользователей.
2. Отсутствие учетных данных для каждого пользователя: Невозможно аутентифицироваться как разные пользователи или передавать контекст пользователя.
3. Отсутствие поддержки многопользовательской системы: Невозможно изолировать учетные данные по арендатору или организации.
4. Только статические токены: Нет поддержки обновления, ротации или обработки истечения срока действия токенов.
5. Аутентификация на уровне сервиса: Аутентифицируется сервис TrustGraph, а не отдельные пользователи.
6. Общий контекст безопасности: Все вызовы инструмента MCP используют одни и те же учетные данные.

Область применения

✅ Подходящие сценарии использования: Развертывания TrustGraph для одного арендатора. Аутентификация от сервиса к сервису (TrustGraph → MCP Server). Среды разработки и тестирования. Внутренние инструменты MCP, доступные системе TrustGraph. Сценарии, в которых все пользователи имеют одинаковый уровень доступа к инструменту MCP. Статические, долгоживущие учетные данные сервиса.

❌ Неподходящие сценарии использования: Системы с несколькими пользователями, требующие аутентификацию для каждого пользователя. Многопользовательские SaaS-платформы с требованиями к изоляции арендаторов. Сценарии федеративной аутентификации (SSO, OAuth, SAML). Системы, требующие передачу контекста пользователя на серверы MCP. Среды, требующие динамическое обновление токенов или короткоживущие токены. Приложения, в которых разные пользователи должны иметь разные уровни разрешений. Требования соответствия для аудиторских журналов на уровне пользователя.

Пример подходящего сценария: Развертывание TrustGraph для одной организации, в котором все сотрудники используют один и тот же внутренний инструмент MCP (например, поиск информации в корпоративной базе данных). Сервер MCP требует аутентификации для предотвращения внешнего доступа, но все внутренние пользователи имеют одинаковый уровень доступа.

Пример неподходящего сценария: Многопользовательская SaaS-платформа TrustGraph, в которой арендатор A и арендатор B должны получать доступ к своим собственным изолированным серверам MCP с отдельными учетными данными. Эта функция НЕ поддерживает управление токенами на уровне арендатора.

Связанные компоненты

trustgraph-flow/trustgraph/agent/mcp_tool/service.py: Сервис вызова инструмента MCP. trustgraph-cli/trustgraph/cli/set_mcp_tool.py: Инструмент командной строки для создания/обновления конфигураций MCP. trustgraph-cli/trustgraph/cli/show_mcp_tools.py: Инструмент командной строки для отображения конфигураций MCP. MCP Python SDK: streamablehttp_client из mcp.client.streamable_http.

Требования

Функциональные требования

1. Токен аутентификации для конфигурации MCP: Конфигурации инструмента MCP ДОЛЖНЫ поддерживать необязательное поле auth-token.
2. Использование токена Bearer: Сервис инструмента MCP ДОЛЖЕН отправлять заголовок Authorization: Bearer {token} при настройке аутентификации.
3. Поддержка CLI: tg-set-mcp-tool ДОЛЖЕН принимать необязательный параметр --auth-token.
4. Отображение токена: tg-show-mcp-tools ДОЛЖЕН указывать, когда настроена аутентификация (маскируется для безопасности).
5. Обратная совместимость: Существующие конфигурации инструмента MCP без аутентификации ДОЛЖНЫ продолжать работать.

Нефункциональные требования

1. Обратная совместимость: Отсутствие изменений, нарушающих работу существующих конфигураций инструмента MCP.
2. Производительность: Отсутствие значительного влияния на производительность вызова инструмента MCP.
3. Безопасность: Токены хранятся в конфигурации (учитывайте последствия для безопасности).

Пользовательские истории

1. Как инженеру DevOps, я хочу настроить токены Bearer для инструментов MCP, чтобы я мог защитить конечные точки серверов MCP.
2. Как пользователю CLI, я хочу устанавливать токены аутентификации при создании инструментов MCP, чтобы я мог подключаться к защищенным серверам.
3. Как системному администратору, я хочу видеть, какие инструменты MCP имеют настроенную аутентификацию, чтобы я мог проверять настройки безопасности.

Проектирование

Архитектура высокого уровня

Расширение конфигурации и сервиса инструмента MCP для поддержки аутентификации с помощью токена Bearer:

1. Добавление необязательного поля auth-token в схему конфигурации инструмента MCP.
2. Изменение сервиса инструмента MCP для чтения токена аутентификации и передачи его в HTTP-клиент.
3. Обновление инструментов командной строки для поддержки установки и отображения токенов аутентификации.
4. Документирование соображений безопасности и лучших практик.

Схема конфигурации

Текущая схема:

{
  "remote-name": "tool_name",
  "url": "http://mcp-server:3000/api"
}

Новая схема (с необязательным токеном авторизации):

{
  "remote-name": "tool_name",
  "url": "http://mcp-server:3000/api",
  "auth-token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Описание полей: remote-name (необязательно): Имя, используемое сервером MCP (по умолчанию - ключ конфигурации). url (обязательно): URL-адрес конечной точки сервера MCP. auth-token (необязательно): Токен для аутентификации.

Поток данных

1. Хранение конфигурации: Пользователь запускает tg-set-mcp-tool --id my-tool --tool-url http://server/api --auth-token xyz123.
2. Загрузка конфигурации: Сервис инструмента MCP получает обновление конфигурации через обратный вызов on_mcp_config().
3. Вызов инструмента: Когда инструмент вызывается: Сервис считывает auth-token из конфигурации (если он присутствует). Создает словарь заголовков: {"Authorization": "Bearer {token}"}. Передает заголовки в streamablehttp_client(url, headers=headers). Сервер MCP проверяет токен и обрабатывает запрос.

Изменения API

Отсутствуют внешние изменения API - только расширение схемы конфигурации.

Детали компонента

Компонент 1: service.py (Сервис инструмента MCP)

Файл: trustgraph-flow/trustgraph/agent/mcp_tool/service.py.

Назначение: Вызов инструментов MCP на удаленных серверах.

Необходимые изменения (в методе invoke_tool()):

1. Проверить наличие auth-token в конфигурации self.mcp_services[name].
2. Создать словарь заголовков с заголовком Authorization, если токен существует.
3. Передать заголовки в streamablehttp_client(url, headers=headers).

Текущий код (строки 42-89):

async def invoke_tool(self, name, parameters):
    try:
        if name not in self.mcp_services:
            raise RuntimeError(f"MCP service {name} not known")
        if "url" not in self.mcp_services[name]:
            raise RuntimeError(f"MCP service {name} URL not defined")

        url = self.mcp_services[name]["url"]

        if "remote-name" in self.mcp_services[name]:
            remote_name = self.mcp_services[name]["remote-name"]
        else:
            remote_name = name

        logger.info(f"Invoking {remote_name} at {url}")

        # Connect to a streamable HTTP server
        async with streamablehttp_client(url) as (
                read_stream,
                write_stream,
                _,
        ):
            # ... rest of method

Измененный код:

async def invoke_tool(self, name, parameters):
    try:
        if name not in self.mcp_services:
            raise RuntimeError(f"MCP service {name} not known")
        if "url" not in self.mcp_services[name]:
            raise RuntimeError(f"MCP service {name} URL not defined")

        url = self.mcp_services[name]["url"]

        if "remote-name" in self.mcp_services[name]:
            remote_name = self.mcp_services[name]["remote-name"]
        else:
            remote_name = name

        # Build headers with optional bearer token
        headers = {}
        if "auth-token" in self.mcp_services[name]:
            token = self.mcp_services[name]["auth-token"]
            headers["Authorization"] = f"Bearer {token}"

        logger.info(f"Invoking {remote_name} at {url}")

        # Connect to a streamable HTTP server with headers
        async with streamablehttp_client(url, headers=headers) as (
                read_stream,
                write_stream,
                _,
        ):
            # ... rest of method (unchanged)

Компонент 2: set_mcp_tool.py (Инструмент конфигурации командной строки)

Файл: trustgraph-cli/trustgraph/cli/set_mcp_tool.py

Назначение: Создание/обновление конфигураций инструмента MCP.

Необходимые изменения:

1. Добавить необязательный аргумент --auth-token в argparse.
2. Включить auth-token в конфигурационный JSON, если он предоставлен.

Текущие аргументы: --id (обязательный): Идентификатор инструмента MCP. --remote-name (необязательный): Удаленное имя инструмента MCP. --tool-url (обязательный): URL-адрес конечной точки инструмента MCP. -u, --api-url (необязательный): URL-адрес API TrustGraph.

Новый аргумент: --auth-token (необязательный): Токен Bearer для аутентификации.

Измененное построение конфигурации:

# Build configuration object
config = {
    "url": args.tool_url,
}

if args.remote_name:
    config["remote-name"] = args.remote_name

if args.auth_token:
    config["auth-token"] = args.auth_token

# Store configuration
api.config().put([
    ConfigValue(type="mcp", key=args.id, value=json.dumps(config))
])

Компонент 3: show_mcp_tools.py (Инструмент отображения командной строки)

Файл: trustgraph-cli/trustgraph/cli/show_mcp_tools.py

Назначение: Отображение конфигураций инструмента MCP.

Необходимые изменения:

1. Добавить столбец "Auth" в таблицу вывода.
2. Отображать "Да" или "Нет" в зависимости от наличия auth-токена.
3. Не отображать фактическое значение токена (безопасность).

Текущий вывод:

ID          Remote Name    URL
----------  -------------  ------------------------
my-tool     my-tool        http://server:3000/api

Новый вывод:

ID          Remote Name    URL                      Auth
----------  -------------  ------------------------ ------
my-tool     my-tool        http://server:3000/api   Yes
other-tool  other-tool     http://other:3000/api    No

Компонент 4: Документация

Файл: docs/cli/tg-set-mcp-tool.md

Необходимые изменения:

1. Документировать новый параметр --auth-token
2. Предоставить пример использования с аутентификацией
3. Документировать соображения безопасности

План реализации

Фаза 1: Создание технической спецификации

[x] Написать подробную техническую спецификацию, документирующую все изменения

Фаза 2: Обновление сервиса MCP Tool

[ ] Изменить invoke_tool() в service.py для чтения auth-token из конфигурации [ ] Создать словарь заголовков и передать его в streamablehttp_client [ ] Протестировать с аутентифицированным сервером MCP

Фаза 3: Обновление инструментов командной строки

[ ] Добавить аргумент --auth-token в set_mcp_tool.py [ ] Включить auth-token в конфигурационный JSON [ ] Добавить столбец "Auth" в вывод show_mcp_tools.py [ ] Протестировать изменения в инструментах командной строки

Фаза 4: Обновление документации

[ ] Документировать параметр --auth-token в tg-set-mcp-tool.md [ ] Добавить раздел "Соображения безопасности" [ ] Предоставить пример использования

Фаза 5: Тестирование

[ ] Проверить, что сервис MCP tool успешно подключается с использованием auth-token [ ] Проверить обратную совместимость (инструменты без auth-token по-прежнему работают) [ ] Проверить, что инструменты командной строки правильно принимают и сохраняют auth-token [ ] Проверить, что команда "show" правильно отображает статус аутентификации

Краткое описание изменений в коде

Файл	Тип изменения	Строки	Описание
service.py	Изменено	~52-66	Добавлено чтение auth-token и построение заголовков
set_mcp_tool.py	Изменено	~30-60	Добавлен аргумент --auth-token и хранение в конфигурации
show_mcp_tools.py	Изменено	~40-70	Добавлен столбец Auth в отображение
tg-set-mcp-tool.md	Изменено	Различные	Документирован новый параметр

Стратегия тестирования

Юнит-тесты

Чтение токена аутентификации: Проверить, что invoke_tool() правильно считывает auth-token из конфигурации Построение заголовков: Проверить, что заголовок Authorization строится правильно с префиксом Bearer Обратная совместимость: Проверить, что инструменты без auth-token работают без изменений Разбор аргументов командной строки: Проверить, что аргумент --auth-token разбирается правильно

Интеграционные тесты

Аутентифицированное подключение: Проверить, что сервис MCP tool подключается к аутентифицированному серверу Комплексное тестирование: Проверить взаимодействие командной строки → хранилище конфигурации → вызов сервиса с auth token Подключение без токена: Проверить, что подключение к неаутентифицированному серверу по-прежнему работает

Ручное тестирование

Реальный сервер MCP: Проверить с фактическим сервером MCP, требующим аутентификацию с использованием токена bearer Рабочий процесс командной строки: Проверить полный рабочий процесс: настройка инструмента с auth → вызов инструмента → проверка успешного выполнения Маскировка отображения: Убедиться, что статус аутентификации отображается, но значение токена не отображается

Миграция и развертывание

Стратегия миграции

Миграция не требуется - это чисто дополнительная функциональность: Существующие конфигурации MCP tool без auth-token продолжают работать без изменений Новые конфигурации могут опционально включать поле auth-token Инструменты командной строки принимают, но не требуют параметр --auth-token

План развертывания

1. Фаза 1: Развернуть основные изменения сервиса в среде разработки/тестирования
2. Фаза 2: Развернуть обновления инструментов командной строки
3. Фаза 3: Обновить документацию
4. Фаза 4: Развертывание в производственной среде с мониторингом

План отката

Основные изменения обратно совместимы - существующие инструменты не затронуты В случае возникновения проблем обработку auth-token можно отключить, удалив логику построения заголовков Изменения в инструментах командной строки являются независимыми и могут быть отменены отдельно

Соображения безопасности

⚠️ Критическое ограничение: Поддержка только однопользовательской аутентификации

Этот механизм аутентификации НЕ подходит для многопользовательских или многопользовательских сред.

Общие учетные данные: Все пользователи и вызовы используют один и тот же токен для каждого инструмента MCP Отсутствие контекста пользователя: Сервер MCP не может различать разных пользователей TrustGraph Отсутствие изоляции арендаторов: Все арендаторы используют одни и те же учетные данные для каждого инструмента MCP Ограничение журнала аудита: Сервер MCP отображает все запросы от одних и тех же учетных данных Область разрешений: Невозможно применять разные уровни разрешений для разных пользователей

Не используйте эту функцию, если: Ваша развертка TrustGraph обслуживает несколько организаций (многопользовательская среда) Вам необходимо отслеживать, какой пользователь получил доступ к какому инструменту MCP Разным пользователям требуются разные уровни разрешений Вам необходимо соблюдать требования аудита на уровне пользователей Ваш сервер MCP применяет ограничения скорости или квоты на уровне пользователя

Альтернативные решения для сценариев с несколькими пользователями/многопользовательской средой: Реализовать распространение контекста пользователя через пользовательские заголовки Развернуть отдельные экземпляры TrustGraph для каждого арендатора Использовать сетевую изоляцию (VPCs, service meshes) Реализовать прокси-слой, который обрабатывает аутентификацию для каждого пользователя

Хранение токенов

Риск: Токены аутентификации хранятся в открытом виде в системе конфигурации

Меры по снижению риска: Задокументировать, что токены хранятся без шифрования Рекомендовать использовать токены с коротким сроком действия, когда это возможно Рекомендовать надлежащий контроль доступа к хранилищу конфигурации Рассмотреть возможность будущей реализации для зашифрованного хранения токенов

Раскрытие токенов

Риск: Токены могут быть раскрыты в журналах или в выходных данных командной строки

Меры по снижению риска: Не записывать значения токенов в журналы (записывать только "аутентификация настроена: да/нет") Команда show в командной строке отображает только маскированный статус, а не фактический токен Не включать токены в сообщения об ошибках

Сетевая безопасность

Риск: Токены передаются по незашифрованным соединениям

Меры по снижению риска: Рекомендовать использовать HTTPS-URL-адреса для серверов MCP Предупреждать пользователей о риске передачи данных в открытом виде по протоколу HTTP

Доступ к конфигурации

Риск: Несанкционированный доступ к системе конфигурации раскрывает токены

Меры по снижению риска: Подчеркнуть важность защиты доступа к системе конфигурации Рекомендовать принцип наименьших привилегий для доступа к конфигурации Рассмотреть возможность ведения журналов аудита для изменений конфигурации (будущая реализация)

Многопользовательские среды

Риск: В многопользовательских развертываниях все пользователи используют одни и те же учетные данные MCP

Понимание риска: Пользователь A и пользователь B используют один и тот же токен при доступе к инструменту MCP Сервер MCP не может различать разных пользователей TrustGraph Нет возможности применить права доступа или ограничения скорости для каждого пользователя Журналы аудита на сервере MCP показывают все запросы от одних и тех же учетных данных Если сессия одного пользователя скомпрометирована, злоумышленник получает тот же доступ к MCP, что и все пользователи

Это НЕ ошибка - это фундаментальное ограничение этой архитектуры.

Влияние на производительность

Минимальные накладные расходы: Создание заголовка добавляет незначительное время обработки Влияние на сеть: Дополнительный HTTP-заголовок добавляет ~50-200 байт на запрос Использование памяти: Незначительное увеличение объема памяти для хранения строки токена в конфигурации

Документация

Пользовательская документация

[ ] Обновить tg-set-mcp-tool.md с параметром --auth-token [ ] Добавить раздел о соображениях безопасности [ ] Предоставить пример использования с токеном типа bearer [ ] Задокументировать последствия хранения токенов

Документация для разработчиков

[ ] Добавить встроенные комментарии для обработки токенов аутентификации в service.py [ ] Задокументировать логику создания заголовков [ ] Обновить документацию схемы конфигурации инструмента MCP

Открытые вопросы

1. Шифрование токенов: Следует ли нам реализовать зашифрованное хранение токенов в системе конфигурации?
2. Обновление токенов: Будущая поддержка потоков OAuth для обновления токенов или ротации токенов?
3. Альтернативные методы аутентификации: Следует ли нам поддерживать Basic auth, API-ключи или другие методы?

Рассмотренные альтернативы

1. Переменные среды для токенов: Хранить токены в переменных среды вместо конфигурации Отклонено: Усложняет развертывание и управление конфигурацией

2. Отдельное хранилище секретов: Использовать специализированную систему управления секретами Отложено: Выходит за рамки первоначальной реализации, рассмотреть возможность будущей реализации

3. Несколько методов аутентификации: Поддержка Basic, API-ключей, OAuth и т.д. Отклонено: Токены типа bearer охватывают большинство сценариев использования, сохраняем простоту первоначальной реализации

4. Зашифрованное хранение токенов: Шифровать токены в системе конфигурации Отложено: Безопасность системы конфигурации является более широкой проблемой, отложить до будущей работы

5. Токены для каждого вызова: Разрешить передачу токенов во время вызова Отклонено: Нарушает разделение ответственности, агент не должен обрабатывать учетные данные

Ссылки

Спецификация протокола MCP HTTP Bearer Authentication (RFC 6750) Текущий сервис инструмента MCP Спецификация аргументов инструмента MCP

Приложение

Пример использования

Настройка инструмента MCP с аутентификацией:

tg-set-mcp-tool \
  --id secure-tool \
  --tool-url https://secure-server.example.com/mcp \
  --auth-token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Отображение инструментов MCP:

tg-show-mcp-tools

ID            Remote Name   URL                                    Auth
-----------   -----------   ------------------------------------   ------
secure-tool   secure-tool   https://secure-server.example.com/mcp  Yes
public-tool   public-tool   http://localhost:3000/mcp              No

Пример конфигурации

Хранится в системе конфигурации:

{
  "type": "mcp",
  "key": "secure-tool",
  "value": "{\"url\": \"https://secure-server.example.com/mcp\", \"auth-token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\"}"
}

Лучшие практики безопасности

1. Использование HTTPS: Всегда используйте HTTPS-адреса для серверов MCP с аутентификацией.
2. Кратковременные токены: Используйте токены с истечением срока действия, когда это возможно.
3. Принцип наименьших привилегий: Предоставляйте токенам минимально необходимые разрешения.
4. Контроль доступа: Ограничьте доступ к системе конфигурации.
5. Ротация токенов: Регулярно обновляйте токены.
6. Журналирование аудита: Отслеживайте изменения конфигурации для выявления событий безопасности.