Шаблон MCP-сервера с аутентификацией Descope

Простой шаблон сервера FastMCP для Render с полной аутентификацией MCP от Descope.

Что включено

• Рабочий MCP-сервер, использующий FastMCP с потоковым HTTP-транспортом

• Полная поддержка авторизации MCP с помощью DescopeProvider из FastMCP и SDK descope-mcp

• Пример инструмента (hello), который возвращает "Hello, world!" и требует наличия определенной области доступа (mcp:greet)

• Blueprint render.yaml для простого развертывания

Примечание: По умолчанию этот шаблон развертывается на бесплатном тарифе Render. Бесплатные сервисы переходят в спящий режим после 15 минут бездействия, что вызывает «холодный старт» длительностью 30-60 секунд при следующем запросе. MCP-клиенты могут выдать ошибку по таймауту во время этой задержки. Для надежного использования перейдите на платный тариф в панели управления Render — тариф Starter поддерживает ваш сервис в постоянно активном состоянии.

Related MCP server: MCP Server Template

Предварительные требования

• Python 3.13+

• uv

• Учетная запись и проект в Descope

Настройка Descope

1. Войдите в консоль Descope.

2. Перейдите в Agentic Identity Hub → MCP Servers.

3. Нажмите + MCP Server, чтобы создать новый MCP-сервер, и дайте ему имя.

4. В разделе MCP Client Registration включите Client ID Metadata Documents (CIMD) и Dynamic Client Registration (DCR). При желании вы можете ограничить разрешенные домены для клиентов, регистрирующихся через CIMD (например, https://claude.ai) — это поле можно оставить пустым.

5. В разделе MCP Server Scopes добавьте область (scope) с именем mcp:greet и простым описанием, например «Приветствие пользователя».

6. Нажмите Create.

7. Разверните раздел Connect your MCP server to Descope на странице подтверждения.

8. Скопируйте Well-Known URL. Он выглядит так:

   https://api.descope.com/v1/apps/agentic/.../.well-known/openid-configuration

   Это ваш DESCOPE_CONFIG_URL.

Примечание: Descope выпускает токены в соответствии с Resource Indicators (RFC 8707), как того требует спецификация MCP. При развертывании на Render или локальном запуске вам нужно будет обновить раздел MCP Server URLs.

Развертывание на Render

Убедитесь, что вы выполнили шаг Настройка Descope перед локальной разработкой, так как вам понадобится ваш DESCOPE_CONFIG_URL.

1. Сделайте форк этого репозитория в свой аккаунт GitHub.

2. Нажмите Deploy to Render (или форкните этот репозиторий на GitHub и импортируйте его как Blueprint в свой аккаунт Render).

   

3. В своих конфигурациях установите переменную окружения, используя значение, полученное на шаге Настройка Descope:

   Ключ	Значение
   DESCOPE_CONFIG_URL	Ваш Well-Known URL из консоли Descope

4. Нажмите Deploy Blueprint.

5. После запуска скопируйте URL вашего сервиса Render (например, https://<your-project>.onrender.com), добавьте в конце /mcp и внесите его в MCP Server URLs в консоли Descope.

Теперь у вас есть удаленно размещенный MCP-сервер с полной поддержкой спецификации авторизации!

Локальная разработка

Убедитесь, что вы выполнили шаг Настройка Descope перед локальной разработкой, так как вам понадобится ваш DESCOPE_CONFIG_URL.

Сначала сделайте форк этого репозитория в свой аккаунт GitHub, затем следуйте инструкциям ниже для настройки окружения.

# Install dependencies
uv sync

# Set required environment variables
export DESCOPE_CONFIG_URL="<your URL from Descope>"
export SERVER_URL="http://localhost:8000"

# Run the server
uv run server.py --transport http --port 8000

При локальном запуске ваш сервер будет доступен по адресу http://localhost:8000/mcp.

Доступные инструменты

Дальнейшие шаги

Теперь, когда все настроено, мы рекомендуем выполнить еще несколько шагов, если вы планируете использовать свой MCP-сервер в продакшене.

Добавление собственных инструментов

Замените или расширьте инструмент hello в файле server.py своей логикой. Для каждого нового инструмента:

1. Определите новую область в консоли Descope в разделе MCP Server Scopes (например, mcp:your-scope).

2. Добавьте инструмент, используя декоратор @mcp.tool().

3. Вызовите require_scopes(token, ["mcp:your-scope"]) внутри тела инструмента для обеспечения контроля доступа.

4. Добавьте новый инструмент и требуемую для него область в таблицу Доступные инструменты выше.

@mcp.tool()
def my_tool() -> str:
    token = validate_token()
    require_scopes(token, ["mcp:your-scope"])
    return "your result"

Использование собственного домена на Render

По умолчанию ваш сервис доступен по адресу https://<your-project>.onrender.com. Чтобы использовать собственный домен:

1. В панели управления Render перейдите в свой сервис → Settings → Custom Domains.

2. Добавьте свой домен и следуйте предоставленным инструкциям по DNS.

3. После подтверждения домена обновите MCP Server URLs в консоли Descope, чтобы использовать ваш собственный домен (например, https://mcp.yourdomain.com/mcp).

4. Изменения в коде не требуются — RENDER_EXTERNAL_URL устанавливается автоматически сервисом Render и будет отражать основной домен.

Защита всех инструментов областями доступа

Проверка require_scopes() намеренно сделана опциональной для каждого инструмента, чтобы вы могли при необходимости добавлять неаутентифицированные инструменты. Для продакшн-сервера хорошей практикой является вызов require_scopes() в каждом инструменте. Вы также можете централизовать это, написав вспомогательную функцию, которая оборачивает validate_token() и require_scopes(), и вызывая ее в начале каждого обработчика инструментов.

Как работает авторизация MCP

1. MCP-клиент (например, Claude Desktop, Cursor) обнаруживает метаданные OAuth из /.well-known/oauth-authorization-server при попытке подключения к вашему MCP-серверу.

2. Клиент динамически регистрируется (через CIMD или DCR) на сервере авторизации и перенаправляет пользователя на поток входа/согласия Descope.

3. После входа Descope выдает подписанный JWT. Клиент включает его в качестве Bearer-токена в каждый запрос MCP.

4. DescopeProvider проверяет JWT с помощью эндпоинта JWKS от Descope перед вызовом любого инструмента.

5. Внутри инструмента validate_token() анализирует утверждения (claims), а require_scopes() проверяет наличие mcp:greet, возвращая ошибку клиенту, если область отсутствует.

Узнать больше

• Render Blueprints

• Авторизация MCP

• FastMCP

• Документация Descope Agentic Identity Hub

• SDK Descope MCP