STARWARCLOUD STARWAR.AI
返回市场
MCP认证逐步指南

MCP认证逐步指南

作者：christian-posta49 星标更新：2025-08-11
安装使用来源：spider==github.com

项目介绍

MCP 认证步骤详解

本仓库演示了如何构建一个具有HTTP传输和JWT认证的MCP（模型上下文协议）服务器，并通过迭代步骤逐步实现。

该仓库是与深入的分步博客文章“MCP授权”配套的。请参阅以下内容：

MCP授权规范要求

下表显示了主要身份提供商对MCP授权规范所需OAuth RFC的支持情况。

RFC要求总结：

  • PKCE：用于代码交换的证明密钥（OAuth 2.1的要求）
  • RFC 8414：OAuth 2.0授权服务器元数据
  • RFC 7591：OAuth 2.0动态客户端注册协议
  • RFC 8707：OAuth 2.0资源指示符
身份提供商PKCERFC 8414RFC 7591RFC 8707
Okta是是是否
Auth0是是基本支持否
Keycloak是是是否
Ping Federate是是是是
ForgeRock是是是基本支持
Google OAuth是否否否
Microsoft Entra是是否否

概览

该项目展示了如何构建一个安全的MCP服务器，包括：

  • 基于FastAPI的HTTP传输
  • JWT令牌认证
  • OAuth 2.0元数据端点
  • 基于范围的授权
  • 基于角色的访问控制

分步进展

步骤1：基本的FastAPI框架

  • 文件：http-transport-steps/src/mcp_http/step1.py
  • 新增内容：带有健康检查端点的基本FastAPI应用程序
  • 关键特性：
    • FastAPI服务器设置
    • 基本健康检查端点（/health）
    • MCP HTTP传输的基础

步骤2：基本的MCP请求处理

  • 文件：http-transport-steps/src/mcp_http/step2.py
  • 新增内容：MCP协议请求/响应处理
  • 关键特性：
    • MCP请求解析和验证
    • 基本的MCP响应结构
    • /mcp端点用于MCP协议通信
    • 类似JSON-RPC的请求处理方式

步骤3：MCP工具和提示定义

  • 文件：http-transport-steps/src/mcp_http/step3.py
  • 新增内容：未执行的MCP工具和提示
  • 关键特性：
    • 工具定义（echo，get_time）
    • 提示定义（greeting，help）
    • 符合MCP协议的工具和提示
    • 尚未实际执行工具

步骤4：MCP工具调度

  • 文件：http-transport-steps/src/mcp_http/step4.py
  • 新增内容：实际工具执行和提示处理
  • 关键特性：
    • 工具调度和执行
    • 提示检索和处理
    • 功能齐全的工作MCP服务器
    • 错误处理无效请求

步骤5：基本的JWT基础设施

  • 文件：http-transport-steps/src/mcp_http/step5.py
  • 新增内容：从文件加载公钥和JWKS端点
  • 关键特性：
    • 从文件加载公钥
    • JWKS（JSON Web Key Set）端点（/.well-known/jwks.json）
    • 外部令牌生成脚本（generate_token.py）
    • JWT基础设施基础

步骤6：JWT令牌验证

  • 文件：http-transport-steps/src/mcp_http/step6.py
  • 新增内容：JWT认证中间件和强制执行
  • 关键特性：
    • JWT令牌验证中间件
    • 对/mcp端点的认证强制执行
    • 从令牌中提取用户上下文
    • 对无效或缺失令牌的适当错误响应

步骤7：OAuth 2.0元数据端点

  • 文件：http-transport-steps/src/mcp_http/step7.py
  • 新增内容：受保护资源和授权服务器的OAuth 2.0元数据
  • 关键特性：
    • /.well-known/oauth-protected-resource端点
    • /.well-known/oauth-authorization-server端点
    • 带有OAuth元数据的增强健康检查端点
    • MCP响应中的OAuth元数据

步骤8：基于范围的授权

  • 文件：http-transport-steps/src/mcp_http/step8.py
  • 新增内容：权限检查和基于角色的访问控制
  • 关键特性：
    • check_permission方法进行范围验证
    • 基于角色的访问控制（管理员、用户、访客）
    • 权限不足时返回403 Forbidden响应
    • 对MCP操作的范围强制执行

步骤9：增强的MCP集成（计划中）

  • 新增内容：在响应中包含用户上下文和认证工具
  • 计划功能：
    • 在MCP响应头/元数据中包含用户上下文
    • 具有用户感知行为的认证工具
    • 增强的MCP协议集成
    • 根据用户身份定制的响应

JWT令牌结构

JWT令牌包括：

  • 用户ID：用户的唯一标识符
  • 范围：权限（例如，mcp:read，mcp:tools，mcp:prompts）
  • 角色：用户角色（例如，admin，user，guest）
  • 过期时间：令牌的有效期

测试

每个步骤都包含一个对应的测试脚本（test_stepX.sh），验证：

  • 基本功能
  • JWT认证（步骤5+）
  • 授权（步骤6+）
  • OAuth元数据（步骤7+）
  • 访问控制（步骤8+）

使用

预备条件

  1. 安装uv：https://docs.astral.sh/uv/getting-started/installation/
  2. 导航到http-transport-steps目录

使用uv运行步骤

# 使用`uv run`运行任意步骤
uv run step1
uv run step2
uv run step3
# ...等等

使用环境配置运行步骤10

步骤10支持基于环境的配置，用于Keycloak和MCP服务器URL。你可以使用--env标志指定一个env文件（不是.env），或者默认使用keycloak_direct.env。

提供了两个示例env文件：

  • keycloak_direct.env（用于直接访问位于localhost:8080的Keycloak）
  • keycloak_proxy.env（用于访问位于localhost:9090的代理）

示例用法：

# 使用特定的env文件（例如，代理）运行步骤10
uv run step10 --env keycloak_proxy.env

如果env文件或环境变量丢失，服务器将回退到合理的默认值（如localhost:8080等）。

运行步骤11的注意事项

  • 你需要先运行步骤10的MCP服务器
  • 你需要允许匿名客户端注册
  • 添加可信主机（查看Keycloak日志以获取正确的IP地址）
  • 对于可信主机策略，不需要匹配URI
  • 允许的范围为mcp:read等以及aud映射器
  • 然后运行步骤11客户端
uv run step11

要使用mcp-inspector：

关于mcp范围的问题： https://github.com/modelcontextprotocol/inspector/issues/587

令牌生成

对于需要JWT认证的步骤5-8，可以使用generate_token.py脚本生成令牌：

uv run python generate_token.py --username alice --scopes mcp:read,mcp:tools
uv run python generate_token.py --username bob --scopes mcp:read,mcp:prompts
uv run python generate_token.py --username admin --scopes mcp:read,mcp:tools,mcp:prompts
uv run python generate_token.py --username guest --scopes ""

Keycloak令牌生成

快速获取用于测试步骤9/Keycloak的令牌：

curl -X POST "http://localhost:8080/realms/mcp-realm/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=mcp-test-client" \
  -d "username=mcp-admin" \
  -d "password=admin123" \
  -d "scope=openid profile email mcp:read mcp:tools mcp:prompts" | jq -r '.access_token'

该脚本将输出一个JWT令牌，可以在Authorization: Bearer <token>头部用于认证请求。

依赖项

  • FastAPI
  • PyJWT
  • cryptography
  • uvicorn

项目使用uv进行依赖管理，并使用pyproject.toml配置。