Reason MCP Server

什么是 Reason MCP Server？

Reason MCP Server 是 Reason 官方托管的端点，让 Claude Code、Codex 或任何 MCP 客户端驱动 Reason（一个自主 AI 软件工程师）：启动编码会话、给你的 Reason 发消息，并跟踪它们创建的 pull request。

Reason 由 Reason Machines 推出，是面向 GitHub 的云端编码智能体。你连接一个仓库、分配 issue，Reason 的智能体就会提交附带证据的 pull request，包括屏幕录像、日志和可直接评审的 diff。Reason 只有一个 MCP 服务器，它为 MCP 客户端提供与 Reason HTTP API 相同的操作：每个工具对应一个 API 操作，受连接的权限范围（scope）限制，并绑定到一个工作区。

如何使用 Reason MCP Server？

该服务器使用 Streamable HTTP 传输，地址为：

https://mcp.reasonmachines.com/mcp

你需要一个 Reason 账号。登录方式有两种：

• OAuth（推荐用于交互式使用）：客户端通过动态客户端注册自行注册，无需 client ID 或 secret。它会打开浏览器，你登录 Reason 并选择一个工作区，之后客户端用刷新令牌续期有效期为一小时的访问令牌。未认证的请求会返回带 WWW-Authenticate 头的 401，这是登录流程的开始，而不是错误。
• API key（用于 CI 或没有浏览器的环境）：在 Reason 的 Settings > API（reasonmachines.com/customize?tab=api）中创建 key，并以 Authorization: Bearer <key> 发送。

Claude Code

claude mcp add --transport http reason https://mcp.reasonmachines.com/mcp

然后在 Claude Code 中运行 /mcp，选择 reason 并登录。没有浏览器时，改为传入你的 key：

claude mcp add --transport http reason https://mcp.reasonmachines.com/mcp --header "Authorization: Bearer $REASON_API_KEY"

Codex

Reason 文档给出的配置：

codex mcp add reason --url https://mcp.reasonmachines.com/mcp
codex mcp login reason

Claude Desktop / claude.ai

添加一个自定义连接器，URL 填写 https://mcp.reasonmachines.com/mcp。client ID 和 secret 留空；客户端会自行注册并打开浏览器让你登录。

Cursor

在 ~/.cursor/mcp.json 或项目的 .cursor/mcp.json 中：

{
  "mcpServers": {
    "reason": {
      "url": "https://mcp.reasonmachines.com/mcp"
    }
  }
}

VS Code

在 .vscode/mcp.json 中：

{
  "servers": {
    "reason": {
      "type": "http",
      "url": "https://mcp.reasonmachines.com/mcp"
    }
  }
}

Reason 还在 GitHub 仓库 reason-machines/reason-plugins 中发布了现成的 Claude Code 和 Codex 插件。

Reason MCP Server 的主要功能

• 由 Reason Machines 运营的官方服务器，提供与 Reason HTTP API 相同的操作。
• 支持带动态客户端注册和 PKCE 的 OAuth，也支持用于无界面场景的 Reason API key。
• 基于 scope 的访问控制：连接只能看到其 scope 允许的工具，例如 run、sessions:read、repos:read 和 org:read。未请求特定 scope 的 OAuth 客户端会获得除 ssh:write 之外的全部 scope。
• 每个连接对应一个工作区，因此工具不需要组织 ID 参数。
• 启动在调用返回后继续运行的会话，并轮询其状态和结果。
• 给已命名的 Reason 发消息并读取回复，以及创建、更新或归档 Reason。
• 令牌受众相互独立：为 HTTP API 签发的令牌不能用于 MCP URL，反之亦然。

Reason MCP Server 的使用场景

• 在编辑器中移交任务：“启动一个 Reason 会话，修复不稳定的 auth 测试，添加回归用例并提交 PR。”
• 查看进行中的工作：“列出我最近的 Reason 会话，告诉我哪些还在运行。”
• 跟进结果：“获取上一个会话的结果，并给我 pull request 链接。”
• 与已命名的 Reason 对话：“问问我们的后端 Reason 为什么夜间导出很慢，并把它的回复读给我。”
• 在 CI 中运行 Reason：使用 API key 和范围较窄的连接，让流水线无需浏览器即可创建会话。

Reason 文档建议从 getSelf（也会显示连接持有的 scope）或 listSessions 开始。createSession 会在后台启动工作：轮询 getSession，直到 status 不再是 running，然后检查 outcome。要给某个 Reason 发消息，先用 listReasons 找到它，再通过 openReasonConversation 获取其会话的 session_id，用 sendSessionMessage 发送，并用 listSessionConversation 读取回复。

Reason MCP Server 常见问题排查

• 返回带 missing_bearer 的 401：这是正常的首次响应，说明客户端尚未登录；请执行客户端的登录步骤。
• GET 返回 405：服务器只响应 POST，没有事件流。
• 返回带 mcp_transport_retired 的 410：你使用的是旧的 /mcp/ara 地址，请改用 https://mcp.reasonmachines.com/mcp。
• 缺少某个工具：你只能看到 scope 允许的工具，而且 tools/list 每页返回 30 个工具，请跟随 nextCursor 翻页。