---
title: "MCP (Model Context Protocol)"
description: "透過 MCP 將 AI 程式助理和開發代理連線至您的 Projectyl 工作區。"
---

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

# MCP (Model Context Protocol)

Projectyl 支援 Model Context Protocol（MCP，模型上下文協定）——這個標準讓
AI 工具可以直接讀取和寫入你的專案資料。你不必再把任務複製到聊天提示詞，
也不用為了 AI 助理而摘要文件——只要連結 Projectyl 一次，AI 就有它需要的
所有內容。

這對已經在用 Claude、Cursor 或其他相容 MCP 工具的團隊特別有用。不是必要
功能，不用也完全不影響你的工作——但如果你經常使用 AI 工具，這正是讓
它們在工作流程中真正派上用場的關鍵。

在底層，Projectyl 採用 OAuth 2.1 搭配 PKCE 授權這些用戶端，每個應用程式
都會取得一份可撤銷的授權，且僅綁定在單一工作區上。

> **Caution**
>
> **重大變更**：Personal Access Token（PAT）已由 OAuth 取代。
> 原有的 PAT 不再有效——請依照以下步驟重新連線您的 MCP 用戶端。

## 支援的用戶端

Projectyl 接受以下 MCP 用戶端的連線（依名稱加入白名單）：

- Claude Desktop
- Claude Code
- Cursor
- Claude.ai 連接器
- MCP Inspector（供開發與測試使用）

其他 MCP 用戶端會在註冊階段被拒絕。如需新增用戶端，請來信
[support@projectyl.app](mailto:support@projectyl.app)。

## 連線用戶端

### Claude Desktop

1. 在 Claude Desktop 的設定中新增一個 MCP 伺服器。
2. 將網址設為 `https://<your-projectyl-domain>/api/mcp`。
3. Claude Desktop 會開啟瀏覽器要求您授權此連線。
4. 如有需要，請登入 Projectyl。
5. 在同意畫面上選擇工作區並點選 **允許**。
6. Claude Desktop 已完成連線，相關工具會顯示於對話介面。

### Claude Code

```bash
claude mcp add --transport http projectyl https://<your-projectyl-domain>/api/mcp
```

使用 `--scope project` 讓連線僅限於目前的程式儲存庫，或使用 `--scope user`
讓所有專案都能使用您帳號底下的這個連線。

接著依照瀏覽器提示完成流程（同意畫面與 Claude Desktop 相同）。

### Cursor

在 Cursor 的設定中新增一個遠端 MCP 伺服器，網址設為
`https://<your-projectyl-domain>/api/mcp`。授權流程完全相同。

## 授權範圍

每筆授權都限定於：

- **單一工作區**。於同意畫面選擇。若要讓同一用戶端連到另一個工作區，
  請重新執行 OAuth 流程並選取其他工作區——這會建立一筆獨立的新授權。
- **讀取或讀寫**。用戶端在授權時會要求所需權限；您會在同意畫面上看到。
- **授權時所用的裝置**。同意流程會記錄瀏覽器的 user agent，方便您在
  設定中辨識各筆授權的來源。

存取權杖的有效期為 1 小時；用戶端會在背景使用長效（30 天）的更新權杖
自動延續——整個更新過程不需要您操作。

## 可用工具

連線完成後，您的 AI 助理即可使用以下工具：

### Workspace
- **whoami** — 檢視目前的使用者與工作區資訊
- **get_workspace_info** — 檢視工作區詳細資料

### Projects
- **list_projects** — 列出所有可存取的專案
- **get_project** — 檢視專案詳細資料
- **list_project_members** — 檢視專案成員與角色

### Tasks
- **list_tasks** — 以篩選和分頁方式列出任務
- **get_task** — 檢視任務及其所有關聯資料
- **create_task** — 建立新任務
- **update_task** — 更新任務

### Documents
- **list_documents** — 以搜尋和分頁方式列出文件
- **get_document** — 檢視文件與完整內容
- **create_document** — 建立新文件
- **update_document** — 更新文件

### Targets
- **list_targets** — 以選用的篩選條件列出目標
- **get_target** — 檢視目標完整詳情
- **create_target** — 建立新目標
- **update_target** — 更新目標

### Dependencies
- **list_task_dependencies** — 檢視任務的前置與後繼相依關係
- **create_task_dependency** — 在兩個任務之間建立相依關係
- **delete_task_dependency** — 移除相依關係

### Other
- **list_comments** — 檢視任務或文件的留言
- **list_states** — 檢視專案的工作流狀態
- **list_labels** — 檢視專案的標籤
- **get_help** — 取得 MCP 工具的使用說明

## 管理連線

前往 **設定 → 已連線的應用程式**，可檢視目前工作區中所有有效的授權。
每筆授權皆可：

- 查看用戶端、權限、連線日期與上次使用時間。
- 撤銷授權。該用戶端下次發送請求時會被要求重新授權。

## 安全性說明

- 權杖在資料庫中以雜湊（SHA-256）形式儲存，絕不以明文保存。
- 撤銷會立即生效——被撤銷的用戶端下一個請求會得到 401。
- 只接受白名單中為每個用戶端所登錄的 redirect URI，以防止冒用。

## 探索端點

若有工具或 MCP 用戶端透過標準 metadata 發現授權設定：

- `/.well-known/oauth-protected-resource`（RFC 9728）
- `/.well-known/oauth-authorization-server`（RFC 8414）

兩者皆為公開端點。

## 疑難排解

**同意畫面顯示「Unknown client」錯誤。** 您使用的 MCP 用戶端不在白名單
中。請來信 [support@projectyl.app](mailto:support@projectyl.app) 尋求協助。

**顯示「Invalid redirect URL」錯誤。** 該用戶端的 redirect URI 與已登錄
的樣式不符，通常是用戶端版本更新後 redirect scheme 改變所致。請來信
[support@projectyl.app](mailto:support@projectyl.app)，我們會更新白名單。

**工具呼叫過一段時間後回傳 401。** 該授權可能已被撤銷，或您已在
Projectyl 中切換工作區。請重新執行用戶端的連線流程。

**先前使用 Personal Access Token 可以用，現在卻回傳 401。** PAT 已由
OAuth 取代。請依照上方步驟重新連線您的 MCP 用戶端。

Source: https://docs.projectyl.app/zh-tw/guides/mcp/index.mdx