# MCP

> 透過 Kanorio 的遠端 MCP 伺服器，將 Claude、ChatGPT、Cursor 與其他 AI 助理連接至 Management API。

> Markdown version of https://kanorio.com/zh-HK/developers/mcp. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp
>
> Translated from the English original: https://kanorio.com/en/developers/mcp.md

Model Context Protocol 伺服器是 AI 助理的 Management API。每個操作都是一個工具，工具名稱即為 [Management API 參考文件](https://kanorio.com/en/developers/management-api) 中的 `operationId`，例如 `posts_create` 或 `site_publish`。權限、錯誤、速率限制與草稿的運作方式與 REST 完全相同。

|  |  |
|---|---|
| 伺服器網址 | `https://app.kanorio.com/api/mcp` |
| 傳輸方式 | 串流式 HTTP |
| 驗證方式 | OAuth 2.1，或 Bearer 個人存取權杖或服務帳戶權杖 |
| 登錄名稱 | `com.kanorio/kanorio` |

## 具備連接器的 AI 助理

Claude、ChatGPT 與其他具備內建連接器的 AI 助理使用 OAuth，因此無需手動處理權杖。

1. 在 AI 助理的連接器設定中，新增一個自訂連接器，並將伺服器網址設定為 `https://app.kanorio.com/api/mcp`。請勿將此網址貼入聊天視窗中。
2. 當 AI 助理開啟授權頁面時，登入 Kanorio，選擇網站與權限，並進行核准。

AI 助理會從 `https://app.kanorio.com/.well-known/oauth-protected-resource` 自動探索其餘資訊。Kanorio 支援動態客戶端註冊與客戶端 ID 中繼資料文件。您可以隨時在帳戶設定中檢視並撤銷已核准的應用程式。

## 使用權杖的程式開發 AI 助理

Cursor、Claude Code、Codex、Gemini CLI、Windsurf 與 VS Code 使用個人存取權杖。請在 [帳戶設定 › API 存取](https://app.kanorio.com/account/api-access) 中建立權杖。選擇工具後，Kanorio 會顯示已自動填入您權杖的設定資訊。

**Cursor** (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "kanorio": {
      "url": "https://app.kanorio.com/api/mcp",
      "headers": { "Authorization": "Bearer knr_pat_..." }
    }
  }
}
```

**Claude Code:**

```bash
claude mcp add --transport http kanorio https://app.kanorio.com/api/mcp --header "Authorization: Bearer knr_pat_..."
```

**VS Code** (`.vscode/mcp.json`):

```json
{
  "servers": {
    "kanorio": {
      "type": "http",
      "url": "https://app.kanorio.com/api/mcp",
      "headers": { "Authorization": "Bearer knr_pat_..." }
    }
  }
}
```

**Codex** (`~/.codex/config.toml`):

```toml
[mcp_servers.kanorio]
url = "https://app.kanorio.com/api/mcp"
http_headers = { "Authorization" = "Bearer knr_pat_..." }
```

請勿將包含權杖的檔案納入版本控制。

## 工具運作方式

- **僅限權杖允許的操作。** `tools/list` 會隱藏權杖權限範圍外的工具。呼叫 `auth_whoami` 可查看權杖權限與任何隱藏的功能。
- **發佈前皆為草稿。** 內容寫入操作會保留為草稿，直到執行 `site_publish`、`posts_publish` 或其他發佈工具為止。
- **結構化結果。** 每個工具都會回傳符合該操作回應結構描述的結構化內容。清單使用 [分頁封裝](https://kanorio.com/zh-HK/developers/basics/pagination)。
- **錯誤。** 失敗的呼叫會回傳 `isError` 與 [錯誤封裝](https://kanorio.com/zh-HK/developers/basics/errors)。`FORBIDDEN`、計劃與模式錯誤屬於限制而非程式錯誤；`details` 欄位會說明使用者需要調整的內容。
- **冪等性。** 支援冪等性的建立操作工具會接收 `idempotencyKey` 引數。請參閱 [冪等性](https://kanorio.com/zh-HK/developers/basics/idempotency)。
- **棄用。** 已棄用工具的說明開頭會標示 `[Deprecated, removed after …; use …]`。

## 伺服器版本

本伺服器遵循語意化版本控制，資訊記錄於 `serverInfo.version` 及 `https://app.kanorio.com/.well-known/mcp/server.json` 中。[變更日誌](https://kanorio.com/en/developers/changelog) 記錄了每個版本的變更。主版本號更新代表現有工具的運作方式可能有所變動，因此快取工具結構描述的客戶端應進行重新整理。