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

# MCP 伺服器

> 將 ChatGPT、Claude、Codex 或其他 AI 助理工具連接到你的 NexRex 資料。

<Note>
  這是與 [Developer API](/zh-Hant/api-reference/introduction) 不同的獨立功能。
  Developer API 會核發組織範圍的金鑰，供你建置整合服務；MCP Server 則是連接
  你的個人帳號，讓 AI 助理工具能查詢你自己的 NexRex 訓練資料。若你是要建置
  應用程式或儀表板，請改看[認證](/zh-Hant/api-reference/authentication)。
</Note>

**MCP Server**（Model Context Protocol，目前為 **Beta** 版）讓 ChatGPT、Claude、Codex 或 Gemini CLI 等 AI 助理工具，能直接在你原本使用的工具中讀取你的 NexRex 訓練資料。

## AI 助理可以存取什麼？

連接後，你的 AI 助理可以：

* **讀取**你的個人檔案、活動、訓練計畫、營養日誌、恢復資料與配速預測
* **讀取**你指導的運動員與群組（如果你有教練權限）
* **草擬**訓練計畫並提出訓練調整建議
* **分析**單一運動員或群組的表現

<Warning>
  AI 助理可以**提出**訓練計畫的變更建議，但**儲存或套用變更時一律需要你明確核准**。未經你許可，不會對你的訓練行事曆做任何更動。
</Warning>

## 連接方式

有兩種連接方式：

* **使用 NexRex 登入（OAuth）**——建議用於 ChatGPT、Claude.ai 與 Claude Code。在你的用戶端中加入伺服器 URL，會觸發瀏覽器登入與核准流程，無需複製權杖。
* **手動權杖**——適用於 Codex、Gemini CLI 或其他不支援 OAuth 的用戶端。在網頁主控台產生權杖，貼到你的設定中。

<Note>
  **授權在哪裡進行？** OAuth 核准發生在**你的瀏覽器中**，當你在用戶端（ChatGPT、Claude 等）加入 MCP 伺服器時。授權流程會將你重新導向至 NexRex，你在那裡登入並點擊 **Allow access（允許存取）**。

  NexRex 網頁主控台的 **設定 → 整合** 僅用於**手動權杖**。你不會在那裡找到「授權」或「允許存取」按鈕——它只為不支援 OAuth 的用戶端產生權杖。
</Note>

***

## 連接 ChatGPT

ChatGPT 支援 OAuth，因此你不需要手動產生權杖。

<Steps>
  <Step title="開啟自訂 GPT 設定">
    在 ChatGPT 中，前往你的個人檔案設定並選擇 **My GPTs** 或 **Custom GPTs**。
  </Step>

  <Step title="新增 MCP 伺服器">
    點擊 **Configure** 或 **Add action**，然後選擇 **Add MCP server** 或類似選項。
    （註：ChatGPT 的 UI 標籤可能隨版本更新而變動。）
  </Step>

  <Step title="輸入伺服器 URL">
    貼上 `https://mcp.nexrex.ai/mcp` 作為 MCP 伺服器 URL。
  </Step>

  <Step title="使用 NexRex 登入">
    ChatGPT 會在你的瀏覽器開啟 NexRex 登入頁面。使用你現有的 NexRex 帳號登入。
  </Step>

  <Step title="核准存取">
    檢視同意畫面，確認提出請求的應用程式名稱與回呼位址。
    若應用程式在你自己的電腦上執行，你會看到本機返回位址的警告。
    確認是你發起的連線後，點擊 **Allow access（允許存取）**。
  </Step>

  <Step title="開始在 ChatGPT 中使用 NexRex">
    連接後，你可以詢問 ChatGPT 關於你訓練資料的問題：

    * 「顯示我最近的活動」
    * 「我目前的訓練計畫是什麼？」
    * 「我朝著比賽目標的進度如何？」
  </Step>
</Steps>

### 中斷與 ChatGPT 的連線

若要移除連線，從你的 ChatGPT 自訂 GPT 或個人檔案設定中刪除該 MCP 伺服器。NexRex 會自動撤銷該連線的權杖。

***

## 連接 Claude

### Claude.ai（網頁版）

Claude.ai 支援與 ChatGPT 類似的 OAuth 連線。

<Steps>
  <Step title="開啟整合">
    在 Claude.ai 中，前往 **Settings** → **Integrations** 或 **Connections**。
  </Step>

  <Step title="新增 MCP 連線">
    點擊 **Add connection** 或 **Add MCP server**，然後輸入 `https://mcp.nexrex.ai/mcp`。
  </Step>

  <Step title="登入並核准">
    你的瀏覽器會開啟 NexRex 登入頁面。登入後在同意畫面點擊 **Allow access（允許存取）**。
  </Step>
</Steps>

### Claude Code（命令列）

Claude Code 是一個同樣支援 OAuth 的命令列工具。

<Steps>
  <Step title="新增 MCP 伺服器">
    在終端機中執行：

    ```bash theme={null}
    claude mcp add --transport http nexrex https://mcp.nexrex.ai/mcp
    ```

    <Warning>
      **不要使用** 設定 → 整合 中顯示的 `--header "Authorization: Bearer ..."` 指令（如果你想要 OAuth）。該指令使用手動權杖，會完全跳過瀏覽器授權流程。若要使用 OAuth，請僅使用上方不含任何 `--header` 旗標的指令。
    </Warning>
  </Step>

  <Step title="授權連線">
    在 Claude Code 中執行：

    ```bash theme={null}
    /mcp
    ```

    這會開啟你的瀏覽器以授權連線。登入 NexRex 並點擊 **Allow access（允許存取）**。
  </Step>

  <Step title="驗證連線">
    Claude Code 會確認連線已啟用。你現在可以詢問關於你 NexRex 資料的問題。
  </Step>
</Steps>

### 中斷與 Claude 的連線

* **Claude.ai**：從 Settings → Integrations 移除連線
* **Claude Code**：在終端機執行 `claude mcp remove nexrex`

***

## 連接 Codex

Codex 不支援 OAuth，因此你需要從 NexRex 網頁主控台產生手動權杖。

<Steps>
  <Step title="在 NexRex 中產生權杖">
    1. 前往 [app.nexrex.ai](https://app.nexrex.ai) 並登入
    2. 導覽至 **設定 → 整合**
    3. 找到 **MCP Server** 區塊（標示 Beta）
    4. 點擊 **Generate token（產生權杖）**

    <Warning>
      完整權杖**只會顯示一次**。請立即複製——你之後無法再看到它。若遺失，你需要重新產生新權杖。
    </Warning>
  </Step>

  <Step title="複製 Codex 設定">
    在同一頁面，選擇 **Codex** 分頁。複製顯示的設定片段：

    ```toml theme={null}
    # ~/.codex/config.toml
    [mcp_servers.nexrex]
    url = "https://mcp.nexrex.ai/mcp"
    http_headers = { "Authorization" = "Bearer YOUR_TOKEN" }
    ```

    將 `YOUR_TOKEN` 替換成你剛才產生的權杖。
  </Step>

  <Step title="更新你的 Codex 設定">
    開啟或建立 `~/.codex/config.toml` 並貼上包含你實際權杖的設定。
  </Step>

  <Step title="驗證連線">
    重新啟動 Codex 或重新載入 MCP 設定。Codex 現在應該可以存取你的 NexRex 訓練資料。
  </Step>
</Steps>

<Note>
  當你的用戶端不支援 OAuth，或你刻意想使用 設定 → 整合 中的權杖而非瀏覽器 OAuth 流程時，請使用此手動權杖方法。
</Note>

***

## 連接其他用戶端（Gemini CLI、自訂工具）

對於不支援 OAuth 的用戶端，或當你想要使用手動權杖時：

<Steps>
  <Step title="在 設定 → 整合 中產生權杖">
    1. 登入 [app.nexrex.ai](https://app.nexrex.ai)
    2. 前往 **設定 → 整合**
    3. 在 **MCP Server** 區塊中點擊 **Generate token（產生權杖）**
    4. 立即複製權杖（只會顯示一次）
  </Step>

  <Step title="複製特定用戶端的設定">
    網頁主控台顯示 **Claude Code**、**Codex** 與 **Gemini CLI** 三個分頁。
    選擇你使用的用戶端分頁並複製設定片段。這些片段使用手動權杖搭配 `Authorization: Bearer YOUR_TOKEN` 標頭。
  </Step>

  <Step title="新增至你用戶端的設定">
    依照你用戶端的文件新增 MCP 伺服器 URL 與權杖。
    大多數用戶端使用 Bearer token 標頭：

    ```
    Authorization: Bearer YOUR_TOKEN
    ```

    將 `YOUR_TOKEN` 替換成你產生的權杖。
  </Step>
</Steps>

<Note>
  當你的用戶端不支援 OAuth（如 Codex 與 Gemini CLI），或你刻意想使用權杖而非 OAuth 瀏覽器流程時，請使用此手動權杖方法。
</Note>

***

## 安全與權杖

### 權杖的有效期限

* 每個手動權杖都有**建立日期**與**到期日**，顯示在 設定 → 整合 中該權杖字尾的旁邊
* 並沒有另外的撤銷操作——若要立即讓某個權杖失效，請重新產生新的權杖

### 重新產生權杖

<Warning>
  當你重新產生權杖時，會**核發一個新權杖**。你原本的權杖在其到期日之前仍可正常使用，但設定頁面只會追蹤最新的一組。若你重新產生權杖，請務必更新所有正在使用舊權杖的 AI 助理設定。
</Warning>

### 最佳實務

* **絕不將權杖提交到版本控制**——像對待密碼一樣對待它們
* **不要分享權杖**——每個權杖都是個人的，且與你的 NexRex 帳號綁定
* **若外洩請重新產生**——如果你不小心暴露了權杖，請立即重新產生

### OAuth 安全性

OAuth 連線使用 **PKCE**（Proof Key for Code Exchange）與**輪替更新權杖**來增強安全性。若 NexRex 偵測到已輪替的更新權杖被重複使用，會撤銷整個連線，你必須重新連接。

***

## 使用 MCP 連線

### 尋找你自己的運動員資料

`get_current_user` 工具會回傳你連接帳號的身分資訊：

```json theme={null}
{
  "user_id": "usr_8f2k...",
  "athlete_id": "usr_8f2k...",
  "email": "you@example.com",
  "display_name": "Jamie Chen",
  "roles": ["coach"],
  "org_id": "org_x1y2...",
  "profile_available": true
}
```

<Tip>
  \*\*給教練：\*\*你自己的帳號可能不在你的運動員名冊中，因此名冊搜尋可能找不到你。請要求你的 AI 助理先呼叫 `get_current_user`，並使用回傳的 `athlete_id` 來取得你自己的個人檔案、訓練計畫與活動。
</Tip>

***

## 疑難排解

### 「授權失敗」或登入迴圈

* **OAuth 用戶端（ChatGPT、Claude）**：移除連線並重新連接
* **手動權杖用戶端（Codex、Gemini）**：在 設定 → 整合 中重新產生權杖並更新你的設定

### 「權杖過期」

手動權杖有到期日。前往 設定 → 整合 重新產生權杖，然後更新你的用戶端設定。

### 「帳號錯誤」或「看不到我的資料」

確認你在授權 OAuth 連線時登入了正確的 NexRex 帳號，或你的手動權杖是從正確的帳號產生的。

### 用戶端不支援 OAuth

如果你的 AI 助理不提供 OAuth，或你找不到 MCP 連線選項，請改用**手動權杖**方法。在 設定 → 整合 中產生權杖，並依照你用戶端的文件說明新增使用 bearer token 的 MCP 伺服器。