带有 Descope 身份验证的 MCP 服务器模板

一个适用于 Render 的简单 FastMCP 服务器模板，具有由 Descope 提供的完整 MCP 身份验证。

包含内容

• 一个使用 FastMCP 和 Streamable HTTP 传输的工作 MCP 服务器

• 通过 FastMCP 的 DescopeProvider 和 descope-mcp SDK 提供完整的 MCP 授权支持

• 一个示例工具 (hello)，它返回 "Hello, world!" 并强制执行工具级范围要求 (mcp:greet)

• 一个用于轻松部署的 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 下，添加一个名为 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。

注意： 根据 MCP 规范的要求，Descope 签发的令牌遵循资源指示符 (RFC 8707)。当您在 Render 上部署或在本地运行时，您需要更新 MCP 服务器 URL 部分。

在 Render 上部署

请确保在本地开发之前已完成 Descope 设置 步骤，因为您需要您的 DESCOPE_CONFIG_URL。

1. 将此存储库 fork 到您的 GitHub 账户。

2. 点击 Deploy to Render（或在 GitHub 上 fork 此存储库并将其作为蓝图导入您的 Render 账户）。

   

3. 在您的指定配置中，将环境变量设置为在 Descope 设置 步骤中获得的值：

   键	值
   DESCOPE_CONFIG_URL	您从 Descope 控制台获得的 Well-Known URL

4. 点击 Deploy Blueprint。

5. 服务上线后，复制您的 Render 服务 URL（例如 https://<your-project>.onrender.com），附加 /mcp，并将其添加到 Descope 控制台的 MCP Server URLs 中。

您现在拥有一个支持完整身份验证规范的远程托管 MCP 服务器！

本地开发

请确保在本地开发之前已完成 Descope 设置 步骤，因为您需要您的 DESCOPE_CONFIG_URL。

首先，将此存储库 fork 到您的 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 服务器投入生产，我们建议采取以下几个步骤。

添加您自己的工具

用您自己的逻辑替换或扩展 server.py 中的 hello 工具。对于每个新工具：

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. 域名验证后，更新 Descope 控制台中的 MCP Server URLs 以使用您的自定义域名（例如 https://mcp.yourdomain.com/mcp）。

4. 无需更改代码 - RENDER_EXTERNAL_URL 由 Render 自动设置，并将反映主域名。

使用范围保护所有工具

require_scopes() 检查是有意为每个工具选择性加入的，因此您可以根据需要添加未经身份验证的工具。对于生产服务器，在每个工具中调用 require_scopes() 是一种很好的做法。您还可以通过编写一个包装 validate_token() 和 require_scopes() 的辅助函数并在每个工具处理程序的顶部调用它来集中处理此操作。

MCP 身份验证的工作原理

1. MCP 客户端（例如 Claude Desktop、Cursor）在尝试连接到您的 MCP 服务器时，会从 /.well-known/oauth-authorization-server 发现 OAuth 元数据。

2. 客户端动态注册（通过 CIMD 或 DCR）到授权服务器，并将用户重定向到 Descope 的登录/同意流程。

3. 登录后，Descope 签发一个签名的 JWT。客户端在每个 MCP 请求中将其作为 Bearer 令牌包含在内。

4. DescopeProvider 在调用任何工具之前使用 Descope 的 JWKS 端点验证 JWT。

5. 在工具内部，validate_token() 解析声明，require_scopes() 检查是否存在 mcp:greet，如果不存在，则向客户端返回错误。

了解更多

• Render 蓝图

• MCP 授权

• FastMCP

• Descope Agentic Identity Hub 文档

• Descope MCP SDK