HTTP OAuth MCP Server

🌊 HTTP + SSE MCP-сервер с OAuth

Введение

В этом репозитории представлена эталонная реализация для создания удаленного сервера MCP, поддерживающего потоковые протоколы HTTP и SSE, авторизованные с помощью OAuth на основе спецификации MCP.

Обратите внимание, что сервер MCP в этом репозитории логически отделен от приложения, которое обрабатывает отчеты SSE + HTTP-транспорта, а также от OAuth.

В результате вы можете легко создать ответвление этого репозитория и подключить собственный сервер MCP и учетные данные OAuth для получения рабочего сервера SSE/HTTP + OAuth MCP с собственным функционалом.

Но почему?

Отличный вопрос! Спецификация MCP добавила спецификацию авторизации на основе OAuth 25 марта 2025 года. В настоящее время, по состоянию на 1 мая 2025 года:

• Typescript SDK содержит множество строительных блоков для создания сервера MCP с авторизацией OAuth и потоковой передачей HTTP, но нет документации или руководства по созданию такого сервера.
• Python SDK не содержит ни реализации потокового HTTP-транспорта, ни реализации строительных блоков OAuth, которые присутствуют в TypeScript SDK.
• Потоковый HTTP-транспорт в целом не поддерживается хост-приложениями MCP, такими как Cursor и Claude Desktop, хотя его можно интегрировать непосредственно в агенты, написанные на JavaScript, с использованием класса StreamableHttpClientTransport из JS/TS SDK.

В Naptha AI мы действительно хотели создать MCP-сервер с авторизацией OAuth на потоковом HTTP-транспорте и не смогли найти никаких референтных реализаций, поэтому решили создать его самостоятельно!

Зависимости

Bun , быстрая все-в-одном среда выполнения JavaScript, является рекомендуемой средой выполнения и менеджером пакетов для этого репозитория. Ограниченное тестирование совместимости было проведено с npm + tsc .

Обзор

В этом репозитории содержится следующее:

1. MCP-сервер, который вы можете легко заменить на свой собственный
2. Приложение express.js, которое управляет транспортами SSE и Streamable HTTP , а также авторизацией OAuth.

Это экспресс-приложение — то, к чему вы подключаете свои учетные данные и сервер MCP.

Обратите внимание, что хотя это экспресс-приложение реализует требуемые конечные точки OAuth, включая /authorize и конечную точку метаданных сервера авторизации ( RFC8414 ), оно не реализует сервер авторизации OAuth!

Этот пример проксирует OAuth на вышестоящий сервер OAuth, который поддерживает динамическую регистрацию клиентов ( RFC7591 ). Чтобы использовать этот пример, вам понадобится собственный сервер авторизации. Мы рекомендуем использовать Auth0 ; см. раздел «Настройка OAuth» ниже.

Настройка вашего сервера

Заметки об OAuth и динамической регистрации клиентов

Для использования этого примера вам понадобится сервер авторизации OAuth. Не реализуйте это самостоятельно! Для создания нашей демонстрации мы использовали Auth0 — это отличный вариант, хотя есть и много других.

Спецификация MCP требует поддержки необычной функции OAuth, в частности RFC7591 , динамической регистрации клиентов. Спецификация MCP указывает, что клиенты и серверы MCP должны поддерживать протокол динамической регистрации клиентов, чтобы клиенты MCP (где бы ни находился ваш клиентский транспорт) могли получать идентификаторы клиентов без регистрации пользователя. Это позволяет новым клиентам (агентам, приложениям и т. д.) автоматически регистрироваться на новых серверах. Более подробную информацию об этом можно найти в разделе авторизации спецификации MCP , но это означает, что, к сожалению, вы не можете просто напрямую проксировать поставщика, такого как Google или GitHub, которые не поддерживают динамическую регистрацию клиентов (они требуют, чтобы вы регистрировали клиентов в своем пользовательском интерфейсе).

Это оставляет вам два варианта:

1. Выберите поставщика OAuth верхнего уровня, например Auth0, который позволяет использовать OIDC IDP, такие как Google и GitHub, для аутентификации и поддерживает динамическую регистрацию клиентов, или
2. реализовать динамическую регистрацию клиента в приложении самостоятельно (т. е. приложение Express становится не просто простым прокси OAuth, а полным или частично полным сервером OAuth). Cloudflare реализовали что-то подобное для своих серверов Workers OAuth MCP, с помощью которых мы можем расширить этот проект позже. Вы можете найти это здесь .

Для простоты мы выбрали первый вариант, используя Auth0.

[!ПРИМЕЧАНИЕ]
Поскольку эта реализация проксирует сервер OAuth upstream, подход по умолчанию пересылки токена доступа с сервера OAuth на клиент будет раскрывать токен доступа upstream пользователя клиенту downstream и хосту MCP. Это не подходит для многих вариантов использования, поэтому этот подход повторно реализует некоторые классы @modelcontextprotocol/typescript-sdk для исправления этой проблемы.

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

Настройка OAuth с Auth0

Чтобы начать работу с Auth0:

1. Создайте учетную запись Auth0 на Auth0.com .
2. Создайте хотя бы одно подключение к IDP, например Google или GitHub. Вы можете узнать, как это сделать, здесь .
3. Продвигайте соединение до соединения на уровне домена . Поскольку новые клиенты OAuth регистрируются каждым клиентом MCP, вы не можете настраивать соединения IDP на основе каждого приложения/клиента. Это означает, что ваши соединения должны быть доступны для всех приложений в вашем домене. Вы можете узнать, как это сделать, здесь .
4. Включить динамическую регистрацию клиентов (auth0 также называет это «динамической регистрацией приложений»). Узнать, как это сделать, можно здесь .

После того, как все это будет настроено, вам понадобится следующая информация:

• ваш идентификатор клиента Auth0
• ваш клиентский секрет Auth0
• ваш домен Auth0-арендатора

Обязательно заполните эту информацию в вашем .env . Скопируйте .env.template , а затем обновите значения с вашими конфигурациями и секретами.

Запуск сервера

Этот репозиторий включает в себя два отдельных автономных сервера:

• реализация потокового HTTP-сервера без сохранения состояния в src/app.stateless.ts . Она поддерживает только потоковый HTTP-транспорт и (теоретически) подходит для развертывания без сервера
• реализация SSE и потокового HTTP с сохранением состояния на src/app.stateful.ts . Это приложение предлагает оба транспорта, но сохраняет состояние в памяти даже при использовании стратегии хранения redis (соединения должны сохраняться в памяти), поэтому оно не подходит для развертывания без сервера или тривиального горизонтального масштабирования.

Вы можете запустить любой из них с помощью bun :

Собираем все вместе

Чтобы протестировать наш сервер MCP с потоковой поддержкой HTTP и OAuth, у вас есть несколько вариантов.

Как отмечалось выше, Python MCP SDK не поддерживает эти функции, поэтому в настоящее время вы можете либо подключить наш удаленный сервер к хосту MCP, например Cursor или Claude Desktop, либо напрямую к приложению TypeScript/JavaScript, но не к приложению Python.

Подключение вашего сервера к хосту MCP (Курсор / Клод)

Поскольку большинство хостов MCP не поддерживают ни потоковый HTTP (который превосходит SSE по ряду параметров), ни OAuth, мы рекомендуем использовать пакет npm mcp-remote , который будет обрабатывать авторизацию OAuth и подключать удаленный транспорт к транспорту STDIO для вашего хоста.

команда будет выглядеть так:

У вас есть несколько вариантов для параметра --transport :

• http-first (по умолчанию): сначала пробует HTTP-транспорт, возвращается к SSE, если HTTP-транспорт завершается ошибкой 404
• sse-first : сначала пробует транспорт SSE, возвращается к HTTP, если SSE не удается с ошибкой 405
• http-only : использует только HTTP-транспорт, завершается ошибкой, если сервер его не поддерживает
• sse-only : использует только транспорт SSE, завершается ошибкой, если сервер его не поддерживает

[!ПРИМЕЧАНИЕ] Если вы запускаете версию сервера без сохранения состояния с помощью src/app.stateless.ts , транспорт SSE недоступен, поэтому следует использовать --transport http-only . Не следует ожидать, что транспорт SSE будет работать, если вы используете эту точку входа.

Подключение вашего сервера к вашему агенту

Вы можете подключить свой сервер Streamable HTTP к агенту в JS/TS с помощью StreamableHTTPClientTransport . Однако это не будет работать с серверами, защищенными OAuth. Вместо этого вы должны использовать заголовок Authorization на стороне клиента с действительным токеном доступа на стороне сервера.

Вы можете реализовать это с помощью учетных данных клиента, ключей API или чего-то еще. Этот шаблон не поддерживается в этом репозитории, но он будет выглядеть так с использованием Vercel AI SDK :