# 安裝 SosoAPI：套件、客戶端及 remote MCP

Canonical URL: https://sosoapi.ai/zh-hant/docs/installation

用本機套件或 hosted MCP，將你個 Agent 接上 SosoAPI。呢度有安裝、測試連接同更新步驟。

## 應該安裝邊個 npm 套件？

新安裝用 sosoapi。四個 distributions 都執行同一個 CLI 及 MCP；另外三個係鎖定相同 sosoapi 版本嘅薄別名，唔係獨立 SDK，功能亦冇分別。只需要安裝一個。

本機使用需要 Node.js 20 或以上及 npm／npx；remote MCP 唔需要安裝本機套件。安裝本身唔會授權存取帳戶或發佈。

npm 發行套件

| 套件 | 用途 | 指令 |

| --- | --- | --- |

| sosoapi | 正式 CLI 及 MCP server | npx -y sosoapi --help |

| @sosoapi/cli | 鎖定同版 sosoapi 嘅別名 | npx -y @sosoapi/cli --help |

| sosoapi-cli | 鎖定同版 sosoapi 嘅別名 | npx -y sosoapi-cli --help |

| sosoapi-mcp | 鎖定同版 sosoapi 嘅別名 | npx -y sosoapi-mcp --help |

- [sosoapi](https://www.npmjs.com/package/sosoapi)

- [@sosoapi/cli](https://www.npmjs.com/package/@sosoapi/cli)

- [sosoapi-cli](https://www.npmjs.com/package/sosoapi-cli)

- [sosoapi-mcp](https://www.npmjs.com/package/sosoapi-mcp)

## 連接本機 MCP 客戶端

以下指令建立 core profile 新連接；已有健康連接就直接沿用，唔好重複建立或覆寫。sosoapi 冇指令參數時會啟動 stdio MCP server，等候 stdin 係正常。

Claude Desktop、Cursor 及其他 stdio 客戶端可以喺其 MCP 設定使用以下 JSON。設定位置及主機批准方式取決於客戶端。按需要重新連接或啟動，然後確認目前對話真係列到工具。

```
claude mcp add sosoapi -e SOSOAPI_TOOL_PROFILE=core -- npx -y sosoapi
```

```
codex mcp add sosoapi --env SOSOAPI_TOOL_PROFILE=core -- npx -y sosoapi
```

```
{
  "mcpServers": {
    "sosoapi": {
      "command": "npx",
      "args": [
        "-y",
        "sosoapi"
      ],
      "env": {
        "SOSOAPI_TOOL_PROFILE": "core"
      }
    }
  }
}
```

- [MCP 工具參考文件](https://sosoapi.ai/zh-hant/docs/mcp)

## 用 OAuth 連接 remote MCP

將以下 URL 加入支援 remote MCP、OAuth 及動態客戶端註冊嘅客戶端。喺瀏覽器登入並選擇工作空間及權限，唔需要貼 API key、client ID 或 client secret。HTTP 唔支援本機檔案上傳；請用媒體 URL 匯入或本機 server。

ChatGPT custom apps 及 Claude remote connectors 取決於方案及客戶端設定。呢個係直接自訂連接，唔代表已上架客戶端嘅 app 目錄。

```
https://gqeshlawtcexsapabaui.supabase.co/functions/v1/remote-mcp
```

- [登入及權限](https://sosoapi.ai/zh-hant/docs/authentication)

## 驗證連接而唔發佈

先查 auth status，有需要先完成瀏覽器登入，再讀取工作空間背景及已連接帳戶，核對身份同目標工作空間。安裝、callback 或 tools/list 成功，都唔足以證明指定帳戶可以發佈。

驗證設定唔需要測試帖文。保留現有內容同原本任務，由使用者完成平台授權，並喺要求寫入前檢視確實目的地、內容及時間。

```
npx sosoapi auth status
```

```
npx sosoapi api contract --route /identity-api/workspace/list --summary
```

## 更新或固定版本

用 npx -y sosoapi@latest --help 取得目前 CLI，再重新啟動 MCP 主機。長期設定可喺 args 明確指定所需版本；固定版本別名會保持對應 sosoapi 版本，更新另一個全域安裝唔會更新佢。

將已安裝套件內嘅 contract 同所需操作核對。遇到版本不一致，更新主機實際使用嘅指令，再連接及核對同一操作。唔好為修正 schema 差異而改憑證或擴大權限。

```
npx -y sosoapi@latest --help
```

```
npx sosoapi api contract --summary
```

- [問題排解](https://sosoapi.ai/zh-hant/docs/troubleshooting)