Руководство по реализации аутентификации MCP-сервера: использование последней спецификации

Несколько дней назад (18 июня 2025 года) команда MCP (Model Context Protocol) выпустила последнюю версию MCP Spec (2025-06-18). Это обновление включает ключевое изменение в спецификации аутентификации. MCP-серверы больше не будут выдавать токены доступа как Authorization Server. Вместо этого они будут потреблять токены доступа и предоставлять ресурсы как Resource Server.

Будучи одним из поддерживающих MCP Auth (библиотека аутентификации для MCP Server — plug-and-play), я реализовал поддержку последней спецификации MCP auth в этом проекте. На основании своего практического опыта я покажу тебе, как реализовать аутентификацию для своего MCP Server в соответствии с новейшей спецификацией.

Эта статья поможет тебе:

• Понять, как работает MCP auth по новой спецификации MCP auth
• Разобраться, что MCP-серверы должны реализовать в роли Resource Server согласно требованиям MCP auth spec
• Давать рекомендации по реализации поддержки аутентификации, которая отвечает новейшим требованиям MCP auth spec для твоего MCP Server
• Выявить частые ошибки и вопросы безопасности при внедрении MCP auth spec

Пожалуйста, обрати внимание, что статья:

• Предполагает, что читатель знаком с базовыми принципами JWT (JSON Web Token). Структура JWT, верификация подписи и прочее подробно не рассматривается. За деталями смотри Auth Wiki - JWT
• Не рассматривает в деталях отдельные RFC, от которых зависит спецификация MCP auth. Описываются только необходимые для соответствия реализации согласно этим RFC
• Не содержит описание реализации клиентов MCP и Authorization server, а также их взаимодействия. Обычно это реализуется сторонними LLM-клиентами и провайдерами авторизационных серверов, поддерживающими MCP по спецификации MCP. Разработчики MCP Server не должны и не могут вмешиваться в эти реализации. За подробностями смотри OAuth Client и Authorization Server
• Все упомянутые в статье токены доступа считаются JWT, так как это наиболее распространённый на рынке формат. Другие типы токенов требуется использовать согласно документации поставщика авторизационного сервера.

Как работает MCP auth?#

Согласно последней MCP auth spec, процесс аутентификации MCP выглядит так:

1. MCP-клиент запрашивает ресурсы с MCP-сервера по адресу https://github-tools.com. Так как пользователь ещё не вошёл в систему, заголовок авторизации HTTP не содержит access token.

2. MCP-сервер не может получить токен доступа из запроса клиента. Он возвращает ошибку HTTP 401 клиенту, добавляя в ответ заголовок WWW-Authenticate, в котором содержится URL к resource metadata сервера (значение поля resource_metadata).

3. MCP-клиент извлекает значение resource_metadata из заголовка WWW-Authenticate (например: https://github-tools.com/.well-known/oauth-protected-resource). Затем MCP-клиент запрашивает по этому адресу resource metadata как у Resource Server. Эти метаданные могут содержать поля типа authorization_servers и scopes_supported, которые помогают клиенту понять, как получить access token и с какими разрешениями.

4-8. MCP-клиент запрашивает метаданные авторизационного сервера по URL из resource metadata, проходит OAuth 2.1 flow с этим сервером и по завершении получает токен доступа.

9. MCP-клиент с полученным access token снова запрашивает ресурс у MCP-сервера.

10. MCP-сервер проверяет валидность токена и возвращает запрошенный ресурс. Далее вся коммуникация клиента и сервера идёт с переданным токеном.

Далее по шагам разберём реализацию auth-механизма MCP-сервера по указанной схеме.

Обработка неавторизованных запросов: возвращаем 401 и заголовок WWW-Authenticate#

Как показано выше, если MCP-клиент отправляет запрос без access token, MCP-сервер возвращает HTTP 401 Unauthorized и заголовок WWW-Authenticate с URL метаданных сервера.

Согласно обработке ошибок спецификации MCP auth, не только при отсутствии access token, но и при получении сервером невалидного токена также возвращаем 401 с заголовком WWW-Authenticate.

Ключевой вопрос — как правильно построить этот заголовок?

Согласно RFC9728, раздел 5.1, заголовок WWW-Authenticate должен содержать параметр resource_metadata, указывающий на URL метаданных защищённого ресурса.

Базовый формат:

Здесь Bearer — схема аутентификации, обозначающая, что требуется bearer-токен для доступа по OAuth 2.0 (см. MDN). Следом указывается полный URL endpoint для resource metadata твоего MCP-сервера.

Пример кода:

Получив такую ошибку 401, MCP-клиент обратится по значению resource_metadata для получения resource metadata у MCP-сервера и на их основании инициирует запрос к нужному авторизационному серверу за токеном доступа.

Теперь понятно, когда нужно возвращать 401 и что в WWW-Authenticate должна быть ссылка на метаданные. Следующий шаг — как строить этот URL и что туда помещать.

Реализация механизма discovery of resource metadata#

Согласно схеме MCP auth, получив ошибку 401, MCP-клиент делает запрос к метаданным ресурса. Следовательно, твой MCP Server как Resource Server должен реализовать endpoint для отдачи resource metadata.

Определяем путь к endpoint метаданных#

В OAuth как идентификатор ресурса используется URL. Он называется "resource indicator". По RFC9728 metadata должны размещаться под определённым путём /.well-known.

Если твой MCP Server предоставляет только одну услугу (например, https://github-tools.com), endpoint метаданных будет таким:

Если на одном сервере размещено несколько сервисов:

• https://api.acme-corp.com/github — сервис интеграции GitHub
• https://api.acme-corp.com/slack — сервис Slack
• https://api.acme-corp.com/database — сервис работы с базой данных

Метаданные расположены по адресам:

• https://api.acme-corp.com/.well-known/oauth-protected-resource/github
• https://api.acme-corp.com/.well-known/oauth-protected-resource/slack
• https://api.acme-corp.com/.well-known/oauth-protected-resource/database

Плюс такого подхода — для каждого сервиса можно настроить свои права и авторизационные серверы. Например:

• GitHub-сервис: сервер авторизации GitHub, права github:read, github:write
• Slack-сервис: OAuth сервер Slack, права slack:channels:read, slack:messages:write
• Database-сервис: внутренний сервер авторизации организации, право db:query

В целом паттерн endpoint метаданных:

Получаем URL endpoint метаданных из идентификатора ресурса:

Формируем ответ resource metadata#

Когда определён путь endpoint, реализуй возврат JSON-метаданных по RFC9728.

В реальной работе важны четыре поля:

Во-первых, поле resource — идентификатор ресурса, должен совпадать с адресом ресурса, который запрашивает MCP-клиент.

Затем поле authorization_servers — массив авторизационных серверов, из которых MCP-клиент получает токены. По OAuth 2.0 Resource Metadata (RFC 9728), это поле опционально, но в MCP-спеке обязательно — иначе клиент не сможет понять, куда отправлять запросы авторизации.

Третье — scopes_supported: все поддерживаемые этим сервером области полномочий (scopes).

Четвёртое — bearer_methods_supported, показывает, как сервер принимает токены доступа. Обычно это ["header"], то есть клиент MCP должен передавать токен в HTTP-заголовке Authorization.

Пример. Конфигурируем metadata для MCP-сервера https://github-tools.com:

Здесь MCP-клиент видит, что для доступа к https://github-tools.com ему нужен токен авторизации от https://auth.github-tools.com, с разрешениями github:read, github:write, repo:admin, и что токен передаётся в заголовке Authorization.

В большинстве случаев этих полей достаточно для работы клиента. Для особых случаев смотри полный перечень в RFC9728.

Валидация access token#

Получив токен доступа от авторизационного сервера, MCP-клиент использует его для обращения к твоему MCP-серверу.

MCP-сервер обязан:

1. Валидировать токен не по данным из самого токена, а используя настройки сервера.
2. Проверять, что audience токена — сам MCP-сервер (то есть токен получен именно под этот ресурс).
3. Корректно валидировать scope.

Валидация токена по конфигурации MCP Server#

Часто разработчики берут issuer (авторизационный сервер) из самого токена, особенно если в metadata несколько серверов, например:

Если просто брать issuer из непроверенного токена, злоумышленник может выдать "лёгкий" токен от поддельного сервера, и твоя валидация его примет. Чтобы избежать этого:

• Если настроен только один авторизационный сервер — жестко валидируй токен только по нему.
• Если несколько — извлекай issuer из токена и ищи его в списке из конфигурации сервера. Если такого нет — отклоняй токен.

Обязательно валидируй issuer.

Пример с использованием jose JWT:

Проверка audience токена#

Token Audience Binding и Validation требует: клиент в запросе токена сообщает, под какой ресурс будет использоваться токен (ресурс указываем в параметре resource). Сервер авторизации прописывает этот ресурс в поле audience (aud) токена. Далее сервер MCP обязан проверить, что audience совпадает с его идентификатором ресурса.

Этот механизм основан на Resource Indicators for OAuth 2.0 (RFC 8707). Схема такая:

1. Клиент в запросе на токен в авторизационный сервер указывает параметр resource (например, https://github-tools.com)

2. Сервер авторизации привязывает этот адрес к токену, указывая его в поле aud внутри JWT

3. MCP-сервер, получая токен, обязан валидировать совпадение audience и своего идентификатора ресурса

Пример для MCP-сервера https://github-tools.com:

Проверка audience — важнейший механизм безопасности против злоупотребления токенами. Без него можно получить токен от другого сервиса и с ним запросить ресурсы у тебя, не будучи авторизованным.

Проверка scope#

Если твой MCP-сервер управляет доступом к различным ресурсам, пользователям могут быть доступны разные scopes (области разрешений).

После валидации токена проверь, есть ли необходимый scope:

По MCP auth spec — если у токена нет нужного scope, возвращай 403 Forbidden.

Заключение#

Теперь ты умеешь реализовать аутентификацию для своего MCP-сервера по самой свежей спецификации. Главное — надёжно валидировать токены, корректно формировать метаданные и строго проверять audience.

Если строишь MCP-сервер, попробуй MCP Auth: в библиотеке уже реализованы все описанные в статье функции, что позволит быстро внедрить поддержку аутентификации.

Обсуди свои вопросы на GitHub. Давай развивать экосистему MCP вместе.