MCP OAuth 2.1 с PKCE: защитите свой сервер агентов за 7 шагов

Спецификация MCP от 15 марта 2026 г. блокирует OAuth 2.1 с помощью PKCE в качестве стандарта авторизации для удаленные серверы MCP. Ключи API в переменных среды по-прежнему работают в первый день, но реестр, Claude Desktop, Cursor, VS Code Copilot и Windsurf предпочитают серверы с поддержкой OAuth, когда пользователи просмотрите интеграции. Если ваш сервер все еще запрашивает долгоживущий носитель в файле конфигурации, вы оставляют часть распределения на столе.

Самое сложное — это не сам OAuth; это пять небольших спецификаций, которые составляет поток аутентификации MCP. вместе: OAuth 2.1 (RFC 9700), PKCE (RFC 7636), динамическая регистрация клиентов (RFC 7591), Индикаторы ресурсов (RFC 8707) и метаданные защищенных ресурсов. Каждый из них маленький; проводка вот где команды застревают. Вот путь по порядку.

Шаг 1. Предоставление документа метаданных защищенного ресурса

Файл PRM сообщает клиентам, где находится ваш сервер авторизации, какие области действия вы принимаете и какие идентификатор ресурса, который нужно поместить в aud требовать. Разместите его в /.well-known/oauth-protected-resource в том же источнике, что и ваша конечная точка MCP:

The authorization_servers list — это переход обнаружения. Клиенты получают ваш PRM, следуйте первой записи в документе метаданных AS и создайте оттуда URL-адрес авторизации. Ограничьте список одной записью, если только вы не управляете федерацией; несколько эмитентов вводят клиента в заблуждение и ничто в спецификации этого не требует.

Шаг 2. Опубликуйте метаданные сервера авторизации.

Ваш поставщик удостоверений (Auth0, Okta, Clerk, Cloudflare Access или самостоятельная Hydra) обслуживает метаданные AS в /.well-known/oauth-authorization-server. Клиенты MCP потребляют его чтобы узнать конечные точки авторизации и токена, поддерживаемые типы разрешений и расположение JWKS. для проверки токена:

Три поля, которые требует спецификация: code_challenge_methods_supported должен включать S256; grant_types_supported должен включать authorization_code и refresh_token; registration_endpoint должен присутствовать, если вы поддерживаете динамические клиенты. Пропустить кого-нибудь и Claude Desktop пометит сервер как несоответствующий во время установки.

Шаг 3. Создайте пару PKCE на клиенте.

PKCE — это 20 строк клиентского кода, и он убивает класс перехвата кода авторизации атака. Сгенерируйте 32 случайных байта, закодируйте их в base64url в верификатор, SHA-256 в верификатор. в вызов и отправьте вызов с запросом на авторизацию:

The resource Параметр (RFC 8707) упускается из виду большинством реализаций. Без токен, созданный для вашего сервера MCP, может быть воспроизведен для любого другого API, который доверяет тот же эмитент; с этим, aud утверждение привязывает токен к идентификатору вашего ресурса и ничто другое не принимает это.

Шаг 4: Обменяйте код на токены

После обратного перенаправления клиент отправляет POST код и исходный верификатор токена. конечная точка. Сервер авторизации пересчитывает SHA-256 верификатора и сравнивает его с сохраненный вызов; если они совпадают, вы получаете токен доступа:

Сохраните токен обновления в безопасном хранилище (связка ключей, диспетчер учетных данных Windows, Linux). libsecret) и удалить верификатор из хранилища сеансов в момент успешного обмена. Доступ токены живут от 5 до 60 минут; Токены обновления живут дольше, но все равно должны меняться при использовании.

Шаг 5. Проверьте токен носителя при каждом запросе MCP.

Потоковый HTTP упрощает проверку токена: каждый HTTP-запрос содержит Authorization заголовок, поэтому ваш сервер MCP проверяет его в промежуточном программном обеспечении перед отправка вызова инструмента. Получите JWKS один раз, кэшируйте его и проверьте эмитента, аудиторию и срок действия при каждом вызове:

Три утверждения, которые выявляют настоящие ошибки: iss закрепляет эмитента; aud закрепляет ресурс (предотвращает воспроизведение между ресурсами); exp ловит устаревшие токены. Не принимайте токены без них; «Я подтвердил подпись» — это не то же самое, что «Я подтвердил утверждения».

Шаг 6. Включите каждый инструмент в области, указанные в его аннотациях.

Конструкция OAuth 2.1 без области действия дает вам двоичный доступ: либо клиент может вызывать каждый инструмент, либо нет. Система аннотаций MCP закрывает этот пробел, позволяя каждому инструменту объявлять свои области действия. потребности. Обработчик считывает аннотации и области токена во время вызова:

Разделяйте деструктивные области и области только для чтения. Пользователь, предоставивший tools:read чтобы запуск еженедельного отчета не должен быть выполнен send_email из того же токена. Claude Desktop и Cursor отображают запрошенные области на экране согласия, поэтому разделение делает UX честен в отношении того, что может сделать клиент.

Шаг 7. Поддержка динамической регистрации клиентов

Динамическая регистрация клиента позволяет клиенту MCP самостоятельно зарегистрироваться на вашем сервере авторизации. без заполнения формы человеком. Курсор или Claude Desktop отправляет запрос на регистрацию, получает client_idи немедленно запускает поток OAuth:

Это часть, которая переводит ваш сервер MCP от «вставки ключа API в файл конфигурации» к «нажмите «Подключиться» в курсоре и предоставьте доступ». Стоит работать, если ваш сервер общедоступен; пропускаемый если вы отправляете товар только небольшому кругу известных клиентов.

Проверьте весь поток от начала до конца

Как только все части будут на своих местах, полный вызов инструмента MCP будет выглядеть так же, как любой другой вызов с аутентификацией на предъявителя. HTTP-запрос:

Если ты видишь 401 с WWW-Authenticate: Bearer resource_metadata="...", клиент знает, где найти вашу настройку аутентификации и повторно запустить поток. Этот заголовок является рукопожатие, которое делает возможным автоматическое обновление токена и повторное подключение после отзыва.

Шпаргалка по проектированию объема

Ключевые выводы

• OAuth 2.1 требует PKCE. Неприятно иметь; каждый поток кода аутентификации несет в себе верификатор и вызов, иначе он не соответствует спецификациям.
• ФРМ в /.well-known/oauth-protected-resource является точкой входа. Клиенты узнают о вашей настройке аутентификации по этому URL-адресу; пропустите его, и клиенты не смогут выполнить автоматическую настройку.
• Используйте resource параметр (RFC 8707). Закрепляет аудиторию токена на ваш сервер MCP, чтобы утекший токен не мог воспроизводиться с другими API.
• Подтвердите эмитента, аудиторию, срок действия и объем. Только проверка подписей межресурсное воспроизведение.
• Разделение разрушительных прицелов. tools:read, tools:invoke:safe, и tools:invoke:destructive предоставить пользователям согласие UX, которое они ожидают от разрешений ОС.
• Динамическая регистрация клиента открывает возможность установки без настройки. Оплатите стоимость внедрения единоразово; каждый новый клиент MCP получает выгоду навсегда.

Сервер MCP, размещенный Botoi по адресу api.botoi.com/mcp работает по той же схеме. Просмотрите Документация по настройке MCP для конфигураций Claude Desktop, Claude Code, Cursor, VS Code и Windsurf. Для подписания JWT и примитивы проверки, используемые вышеприведенным промежуточным программным обеспечением, см. Конечные точки API JWT в интерактивных документах.