必须完成OAuth 2.1授权配置，包括启用原生支持、正确配置auth: oauth21字段、设置授权端点URL、注册PKCE客户端、映射OIDC Claims及触发设备码流程，否则MCP服务器将拒绝请求。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
要让Hermes Agent通过MCP协议安全调用外部工具服务，必须完成OAuth 2.1授权配置，否则客户端将因缺少有效访问令牌而被MCP服务器拒绝请求。
启用MCP OAuth 2.1认证支持
这一步激活Hermes Agent对OAuth 2.1协议的原生支持，使其能识别并处理来自MCP服务器的授权元数据发现响应。
打开~/.hermes/config.yaml文件，在transport.mcp节点下添加auth: oauth21字段。
确保该配置位于transport层级而非backend.auth——【填错位置会导致MCP连接完全跳过授权流程】。
保存文件后，重启Hermes Agent服务使配置生效。
配置MCP服务器授权端点
此步骤告诉Hermes Agent去哪里获取令牌、验证令牌以及发现授权策略，所有URL必须与MCP服务器实际暴露的OAuth 2.1元数据端点严格一致。
在transport.mcp区块中补充以下三项：
authorization_server_url: https://mcp.example.com/oauth2
token_endpoint: https://mcp.example.com/oauth2/token
jwks_uri: https://mcp.example.com/oauth2/jwks.json
注意：这三个地址必须全部可公开访问且返回标准RFC 8414格式的OAuth 2.1元数据；若其中任一地址返回404或格式错误，后续令牌请求将直接失败。
注册客户端并注入PKCE凭据
OAuth 2.1强制要求使用PKCE机制防止授权码劫持，因此不能复用旧版OAuth 2.0的client-secret明文配置方式。
第一步：在MCP服务器控制台创建新客户端，选择“Public Client”类型，并启用urn:ietf:params:oauth:grant-type:device_code和authorization_code两种授权模式。
第二步：复制生成的client_id，粘贴到transport.mcp.client_id字段中。
第三步：执行hermes mcp pkce init命令，该命令会自动生成并安全存储code verifier与code challenge，同时写入~/.hermes/mcp/pkce-state.json。
第四步：将transport.mcp.pkce_state_file设为"~/.hermes/mcp/pkce-state.json"，确保路径存在且可读。
映射OIDC Claims至本地权限
方法一：基于角色声明自动绑定
在transport.mcp.claims_mapping下添加roles: "scp"，表示从ID Token的scp（scope）字段提取权限标签。
方法二：基于自定义声明字段映射
若MCP服务器在ID Token中注入permissions数组，则配置permissions: "permissions"，Hermes Agent将据此构建内部RBAC上下文。
方法三：混合映射（推荐生产环境）
同时启用两项：roles: "groups"用于组织归属，permissions: "x-perms"用于细粒度操作权限，二者叠加决定最终访问能力。
触发设备码授权流程并完成绑定
① 执行hermes mcp auth --mode=device启动设备授权流程。
② 终端输出user_code与verification_uri，手动打开浏览器访问该URI，输入user_code完成身份确认。
③ 等待MCP服务器回调，Hermes Agent自动接收并缓存访问令牌与刷新令牌。
④ 运行hermes mcp test --tool list-tools验证令牌有效性——成功返回工具列表即表示OAuth 2.1授权链路打通。
