> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orriven.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 连接 Agent

> 在 Claude.ai、Claude Code 或任何兼容 MCP 的客户端中配置 orriven MCP 服务并完成 OAuth 2.1 授权。

orriven MCP 服务由统一的 HTTPS 端点提供：

```text theme={null}
https://api.orriven.com/mcp
```

客户端支持端点发现与动态注册机制，基于 OAuth 2.1 授权码流程（配合 PKCE）完成身份认证，无需在本地安装额外的二进制文件。

## 添加连接器

<Tabs>
  <Tab title="Claude.ai">
    <Steps>
      <Step title="进入 设置 → 连接器">
        选择 **添加自定义连接器**。
      </Step>

      <Step title="填写服务地址">
        输入 `https://api.orriven.com/mcp` 并确认。Claude 会向 orriven 发起动态注册并打开授权页面。
      </Step>

      <Step title="确认授权">
        按提示登录，核对授权信息并选择 **允许**。随后在目标对话中启用该连接器即可。
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http orriven https://api.orriven.com/mcp
    ```

    首次调用工具时会自动在默认浏览器中打开授权页面。在无桌面环境或远程会话中，终端将输出授权链接，可在任意具备浏览器的设备上打开完成授权。

    检查连接状态：

    ```bash theme={null}
    claude mcp list
    ```
  </Tab>

  <Tab title="其他客户端">
    任何支持 **Streamable HTTP** 与 **OAuth 2.1**（授权码 + PKCE 及动态客户端注册）的客户端均可直接接入，包括 Cursor、MCP Inspector 及基于官方 MCP SDK 开发的应用。

    在客户端中配置服务地址 `https://api.orriven.com/mcp` 即可自动完成端点发现。暂不支持标准输入输出传输模式（stdio），本地脚本管理请使用[命令行工具](/zh/developers/cli)。
  </Tab>
</Tabs>

## 授权确认

客户端首次使用特定账号连接时，orriven 控制台将展示授权确认界面。

<Frame caption="授权确认界面信息：客户端标识、已验证的重定向 URI 及权限范围。">
  <div style={{ padding: "16px 20px", border: "1px solid #ddd", borderRadius: 8 }}>
    <strong>Claude</strong> 请求代表 <em>[user@example.com](mailto:user@example.com)</em> 访问 orriven。<br />
    重定向目标：<code>claude.ai</code><br />
    <small>授予访问权限后，该应用将获得与当前登录账号一致的开发者与组织管理操作权限。</small>
  </div>
</Frame>

授权时的关键校验项：

* **会话状态**：若当前未登录，需先通过密码或[企业 SSO](/zh/organization/members-roles) 完成身份验证，随后返回授权界面。
* **重定向 URI 校验**：核对界面显示的返回域名是否与客户端提供商一致（如 Claude.ai 对应 `claude.ai`，本地工具对应 `localhost` 地址）。
* **授权操作**：选择 **允许** 即完成授权并签发 OAuth 访问令牌；选择 **拒绝** 则终止授权请求。

授权关系按客户端与账号维度持久保存。后续会话将复用已有凭证，无需重复确认。

<Warning>
  仅授权由本人在当前会话中主动发起的请求。切勿授权来自未知来源或外部消息中的授权链接。
</Warning>

## 初始工作流

完成连接后，可通过组织结构查询工具获取资源标识：

1. **查询组织列表**：调用 `list_organizations` 获取当前账号所属的组织及角色。
2. **查询业务单元**：传入 `organizationId` 调用 `list_workspaces` 获取业务单元 ID。
3. **分发 API 密钥**：传入目标 `workspaceId` 调用 `create_api_key` 或 `create_publishable_key`。

```json theme={null}
// create_api_key 响应示例
{
  "id": "key_101",
  "name": "staging-service",
  "keyId": "ok_3f9a8b1c",
  "secret": "osk_live_9a8b7c6d5e4f3a2b1c0d",
  "createdAt": "2026-08-28T09:00:00Z"
}
```

<Note>
  Secret 密钥明文（`osk_…`）**仅在创建成功时返回一次**。生成后请直接保存至机密管理系统或环境变量中。
</Note>

## 断开连接

如需断开集成，在客户端中移除对应的连接器配置（例如在 Claude.ai 的连接器设置中删除，或运行 `claude mcp remove orriven`）。

访问令牌有效期为 1 小时，使用期间自动续期，闲置 7 天后失效。关于令牌生命周期与吊销策略的详细说明，请参阅[安全与授权](/zh/agent/security)。