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

# 連接 AI 助理（MCP）

> 以瀏覽器授權或 API 金鑰，將 Claude、ChatGPT、Cursor、VS Code 或任何其他 MCP 用戶端連接到你的 Alforse 公司。

Alforse 運行一台 Model Context Protocol（MCP）伺服器，讓 AI 助理可以查詢並操作你的 ERP 資料：品項、銷售、採購、生產、庫存、品質、會計等等。公司裡的每個人都能連接自己的助理，開發人員則可連接程式開發用戶端與指令碼。助理能做的事，只限於它所連接的人員或金鑰被允許做的事。

## 你需要準備什麼

| | 值 |
| - | - |
| 伺服器 URL | `https://app.alforse.com/api/mcp` |
| 傳輸方式 | Streamable HTTP（僅限 `POST`） |
| 方案 | **Business**。在其他方案上，伺服器會拒絕每一次呼叫（請參閱[限制](#limits)）。 |
| 伺服器資訊清單 | `https://app.alforse.com/.well-known/mcp.json`（公開，不含公司資料） |

讓助理登入有兩種方式。請選擇你的用戶端支援的那一種。

| 用戶端 | 連線方式 |
| - | - |
| Claude.ai、Claude Desktop、ChatGPT | **瀏覽器授權（OAuth）。**不需要建立或貼上金鑰。 |
| Claude Code | 兩者皆可。不帶金鑰時，它會在首次使用時啟動瀏覽器授權；也可以傳入 API 金鑰。 |
| Cursor、VS Code、Codex、指令碼與 CI | 在 `Authorization` 標頭中使用 **API 金鑰** |
| 只能執行本機（stdio）伺服器的用戶端 | API 金鑰，透過 `mcp-remote` |

## 以瀏覽器授權連線

事先不需要在 Alforse 中設定任何東西。你在助理中加入伺服器 URL，Alforse 會請你核准這個連線。

**在你的助理中加入伺服器。**

* \*\*Claude Desktop / Claude.ai：\*\***Settings → Connectors → Add custom connector**，然後貼上 `https://app.alforse.com/api/mcp`。
* \*\*ChatGPT：\*\***Settings → Connectors → Add**，然後貼上同一個 URL。ChatGPT 只在部分方案提供自訂連接器。
* **Claude Code：**`claude mcp add --transport http alforse https://app.alforse.com/api/mcp`（不加 `--header`）。

\*\*登入 Alforse。\*\*你的助理會在瀏覽器中開啟一個 Alforse 頁面。若被要求，請登入。

**檢視請求。****授權應用程式**（Authorize Application）頁面會顯示助理的名稱，以及它之後會返回的網站，接著是 "is requesting access to your Alforse account."（正在請求存取你的 Alforse 帳號）。下方會看到所請求的**範圍**（Scope，`mcp:tools`）。

**選擇公司。**在**公司**（Company）下，選擇助理要操作的公司。若你只屬於一家公司，就會直接顯示而不提供選擇。一個連線只在一家公司內運作；若要在另一家公司作業，請重新連線並選擇那一家。

\*\*選取授權。\*\*瀏覽器會返回你的助理，它現在已連線。問它一些簡單的問題來確認，例如「列出我最近的五張銷售訂單」。

NOTE

**誰可以授權**

**授權應用程式**頁面需要你目前公司中**設定**的**更新**權限。沒有這項權限時，你會被送回應用程式並看到 "Access Denied"（拒絕存取）。請向管理員申請該權限，或使用管理員為你建立的 [API 金鑰](https://docs.alforse.com/zh-Hant/docs/building/api-keys.md)。

### 連線能做什麼

* 它**以你的身分，在你所選的公司中**運作，使用的正是你目前的[權限](https://docs.alforse.com/zh-Hant/docs/reference/permissions.md)。如果你的權限改變，助理的權限也會隨之改變。
* 一旦你不再是該公司的啟用中成員，它就會停止運作。
* 公司與使用者永遠來自連線本身。助理無法透過傳入不同的引數來切換公司或冒充他人。

### 登入在幕後如何運作

用戶端會自動處理這些；以下細節是為自行開發用戶端的開發人員而寫。

| 步驟 | 端點 |
| - | - |
| 沒有權杖的呼叫會得到 `401` 與 `WWW-Authenticate: Bearer resource_metadata="https://app.alforse.com/.well-known/oauth-protected-resource"` 的回應 | `/api/mcp` |
| 受保護資源中繼資料 | `https://app.alforse.com/.well-known/oauth-protected-resource` |
| 授權伺服器中繼資料 | `https://app.alforse.com/.well-known/oauth-authorization-server` |
| 用戶端註冊（開放式動態註冊，JSON 本文含 `client_name` 與 `redirect_uris`） | `https://app.alforse.com/register` |
| 核准頁面 | `https://app.alforse.com/authorize` |
| 權杖交換與更新 | `https://app.alforse.com/token` |

* 授權類型（grant types）：`authorization_code` 與 `refresh_token`。回應類型：`code`。
* 使用 `S256` 的 PKCE。公開用戶端（權杖端點驗證方式為 `none`）必須送出 code challenge。
* 權杖端點的用戶端驗證：`client_secret_post` 或 `none`。
* 範圍：`mcp:tools`。
* 授權碼有效 10 分鐘，且只能使用一次。存取權杖有效一小時（`expires_in: 3600`）；用戶端以其更新權杖（refresh token）續期。

## 以 API 金鑰連線

對於無法開啟瀏覽器登入的用戶端，以及指令碼，請使用金鑰。管理員在**設定 → API 金鑰**下建立；金鑰本身帶有自己的權限範圍，並屬於單一公司。建立金鑰與設定範圍的方式，請參閱 [API 金鑰](https://docs.alforse.com/zh-Hant/docs/building/api-keys.md)。

把金鑰放在 `Authorization` 標頭中傳送：

```http theme={null}
Authorization: Bearer alf_your_key_here
```

`alforse-key: alf_your_key_here` 標頭也同樣被接受。

TIP

**指令已替你備好**

建立金鑰時，其對話方塊會在金鑰旁顯示一段 **MCP 指令**（MCP Command）。複製它，即可一步將伺服器加入 Claude Code。

### 用戶端設定

**Claude Code**

```bash theme={null}
claude mcp add --transport http alforse \
  https://app.alforse.com/api/mcp \
  --header "Authorization: Bearer alf_your_key_here"
```

**Cursor**（專案中的 `.cursor/mcp.json`，或合併到你現有的 `mcpServers`）

```json theme={null}
{
  "mcpServers": {
    "alforse": {
      "url": "https://app.alforse.com/api/mcp",
      "headers": { "Authorization": "Bearer alf_your_key_here" }
    }
  }
}
```

**VS Code**（`.vscode/mcp.json`；VS Code 會詢問金鑰，因此不會存進檔案）

```json theme={null}
{
  "inputs": [
    { "id": "alforse-key", "type": "promptString", "description": "Alforse API key", "password": true }
  ],
  "servers": {
    "alforse": {
      "type": "http",
      "url": "https://app.alforse.com/api/mcp",
      "headers": { "Authorization": "Bearer ${input:alforse-key}" }
    }
  }
}
```

**任何其他用戶端：**提供 URL `https://app.alforse.com/api/mcp` 與 `Authorization: Bearer …` 標頭。各用戶端的 URL 欄位名稱不同（例如 `url` 或 `serverUrl`）；請查閱你的用戶端文件。

HEADS UP

**每個用戶端一把金鑰**

每個助理或指令碼都使用獨立的金鑰，並只授予它所需的範圍（唯讀助理只給檢視範圍）。這樣你就能撤銷或縮減其中一把，而不影響其他金鑰。

## 助理看得到的工具

伺服器不是為每項操作提供一個工具，而是提供三個能觸及所有操作的工具：

| 工具 | 功能 |
| - | - |
| `search_tools` | 依關鍵字、模組或風險等級（`READ`、`WRITE`、`DESTRUCTIVE`）搜尋可用的 Alforse 操作。預設回傳 20 筆結果，最多 100 筆。 |
| `describe_tool` | 回傳一項或多項操作的完整合約：說明、所需權限、輸入與回應結構描述。 |
| `call_tool` | 以 JSON 物件的引數執行一項操作。 |

這些操作來自以下範圍：帳號、會計、文件、庫存、開立發票、品項、人員、生產、採購、品質、資源、銷售、設定、共用與使用者。只有 Alforse 明確公開的操作可用；有些操作是刻意不放在伺服器上的。

* 每次呼叫都會經過與應用程式相同的權限檢查，寫入也由同一個服務層驗證。
* 每項操作都帶有風險等級，因此你的助理可以在執行 `WRITE` 或 `DESTRUCTIVE` 操作之前先詢問你。
* 清單讀取預設回傳 **25 列**。助理使用 `limit`（1–100）與 `offset` 分頁。
* 助理會被告知你公司時區的今天日期，因此像「上週」這樣的相對日期能正確解析。

## 限制

| 限制 | 值 |
| - | - |
| 方案 | Business。否則每次呼叫都會回傳 `402`。 |
| 瀏覽器授權的連線 | **每位使用者每分鐘 60 次請求**，由你所有的連線共用 |
| API 金鑰 | 金鑰自己的限制，預設為每分鐘 60 次請求（[詳情](https://docs.alforse.com/zh-Hant/docs/building/api-keys.md#rate-limit)） |
| 存取權杖有效期 | 1 小時，以更新權杖自動續期 |
| 每次清單讀取的列數 | 預設 25，每頁最多 100 |

達到限制時，伺服器會回應 `429`，並附上 `Retry-After` 以及 `X-RateLimit-Limit`、`X-RateLimit-Remaining` 與 `X-RateLimit-Reset` 標頭。請等待 `Retry-After` 所示的秒數後再重試。

## 疑難排解

| 症狀 | 原因 | 解決方式 |
| - | - | - |
| `402` 並顯示 "The MCP server is available on the Business plan. Upgrade to connect an agent to Alforse."（MCP 伺服器僅在 Business 方案提供。升級後即可將代理連接到 Alforse。） | 公司不是 Business 方案。 | 升級方案（請參閱[帳單與訂閱](https://docs.alforse.com/zh-Hant/docs/reference/billing.md)）。連線本身不需要任何變更。 |
| 助理開啟 Alforse 後立刻出現 "Access Denied" | 你缺少**設定**的**更新**權限，而核准頁面需要它。 | 向管理員申請該權限，或改用 API 金鑰連線。 |
| 選取**授權**時出現 "Invalid company"（`403`） | 你不是所選公司的成員。 | 選擇你所屬的公司。 |
| "Invalid redirect URI" 或 "Invalid client" | 用戶端送出了未登錄的返回位址，或其註冊不明。 | 從助理中移除該伺服器再重新加入，讓它重新註冊。 |
| "PKCE required for public clients" | 沒有密鑰的用戶端未送出 code challenge。 | 使用支援 PKCE（`S256`）的用戶端。 |
| 先前正常，之後每次呼叫都出現 `401` | 存取權杖已過期且無法續期、你已不是該公司的啟用中成員，或 API 金鑰已過期或被刪除。 | 重新連線（再次授權）或使用有效的金鑰。 |
| `429` "Rate limit exceeded" | 超過每分鐘允許的請求數。 | 等待 `Retry-After`；請助理改為抓取較少、較大的分頁。 |
| `405` "Method not allowed. Use POST." | 該 URL 被在瀏覽器中開啟，或以 `GET` 呼叫。 | 這是正常的：MCP 用戶端使用 `POST`。請改為將該 URL 加入你的助理。 |
| 工具呼叫因權限錯誤而失敗 | 所連線的使用者或金鑰的範圍不允許該操作。 | 在 Alforse 中授予權限或範圍；自下一次呼叫起生效。 |
| 助理找不到某項操作 | 該操作未在 MCP 伺服器上公開，或搜尋字詞不相符。 | 請助理改依模組（例如「sales」）或欄位名稱搜尋。 |

## 相關內容

**API 金鑰**

為程式開發用戶端、指令碼與 CI 建立金鑰並設定範圍。

[Open](https://docs.alforse.com/zh-Hant/docs/building/api-keys.md)

**權限**

已連線的助理被允許讀取與變更哪些內容。

[Open](https://docs.alforse.com/zh-Hant/docs/reference/permissions.md)

**Slack 中的助理**

在 Slack 中使用 Alforse。

[Open](https://docs.alforse.com/zh-Hant/docs/integrations/assistant.md)

**帳單與訂閱**

你的方案以及如何升級。

[Open](https://docs.alforse.com/zh-Hant/docs/reference/billing.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.