# MCP 伺服器參考

## 可信 Agent 身分與訊息

本機與雲端 MCP 會從 API Key 解析穩定的 `agt_...` 身分碼，並更新最後活躍時間。完整工具集包含 `tokst_agent_list`、`tokst_message_send`、`tokst_message_inbox`、`tokst_message_acknowledge` 與 `tokst_message_close`。廣播會向目標工作區的每個活躍 Agent 建立獨立回執。

## 自動記憶

自動記憶在遠端 MCP、stdio MCP 與本機 CLI 中使用 `tokst_auto_status` 和 `tokst_auto_configure`。本機 ACP 連線負責去識別，並在 ACP 工作階段結束時呼叫已連線的 Agent 整理一條可撤銷記憶。

TokST MCP（Model Context Protocol）伺服器讓 AI 智能體直接與你的記憶系統互動。Claude Code、Codex、Pi、WorkBuddy、ZCode、Qoder、Kimi 與其他 MCP 用戶端都可以透過自然語言儲存、搜尋和管理記憶。

決策、架構、會議紀要和工作建議在 `content` 中使用結構化 Markdown。標題、清單、工作清單、連結、表格和程式碼區塊可以提升審核效率。短事實可使用純文字；金鑰、私鑰、原始推理和暫時工具輸出保留在記憶之外。

## 連線方式

| 方式 | 傳輸協定 | 適用場景 |
|---|---|---|
| **遠端（Streamable HTTP，51 個工具）** | `https://api.tokst.com/mcp` | ChatGPT、Web 智能體、記憶與工作區工作流程 |
| **遠端（SSE 相容，51 個工具）** | `https://api.tokst.com/sse` | 僅支援 SSE 或 stdio 的 MCP 目錄與用戶端 |
| **本機（stdio，51 個工具）** | `tokst local mcp` | 使用獨立安裝器的桌面智能體 |

## 本地 SQLite 模式

先執行一次 `tokst setup --local`，再為 `@tokst/mcp-server` 設定 `TOKST_MODE=local`。此套件會呼叫同一套本地 CLI 執行階段，重用相同工具名稱和 SQLite 設定。

```json
{ "mcpServers": { "tokst-local": { "command": "tokst-mcp", "env": { "TOKST_MODE": "local" } } } }
```

## 遠端設定（適用於 ChatGPT 和遠端智能體）

公開 MCP 清單位於 [`https://api.tokst.com/.well-known/mcp`](https://api.tokst.com/.well-known/mcp)，其中聲明了 Streamable HTTP 入口、OAuth 中繼資料和靜態用戶端的 API 金鑰接入方式。

遠端 MCP 用戶端使用以下端點。首次連接時，用戶端會開啟 TokST 的登入與確認頁面。TokST 使用 OAuth 2.1 授權碼流程與 PKCE，並為已確認用戶端建立穩定的可信智能體身分。

```json
{
  "mcpServers": {
    "tokst": {
      "type": "streamable-http",
      "url": "https://api.tokst.com/mcp"
    }
  }
}
```

遠端端點採用無狀態 Streamable HTTP：每次請求均攜帶驗證資訊，可由任一健康執行個體處理。它回傳 JSON 工具回應，不需維護持久 MCP 工作階段 ID。

授權伺服器在 `/.well-known/oauth-protected-resource` 與 `/.well-known/oauth-authorization-server` 提供 OAuth 中繼資料。支援動態用戶端註冊的用戶端可自動註冊。

### API 金鑰遠端設定

WorkBuddy、ZCode、Qoder、Kimi、CI 與其他使用靜態 MCP 設定的用戶端可透過專用 API 金鑰連線。在[儀表板 API 金鑰](https://tokst.com/dashboard/api-keys)建立金鑰後，填入以下設定：

```json
{
  "mcpServers": {
    "tokst": {
      "type": "streamable-http",
      "url": "https://api.tokst.com/mcp",
      "headers": {
        "Authorization": "Bearer tk_live_your_api_key"
      }
    }
  }
}
```

每個用戶端使用獨立金鑰。金鑰儲存在用戶端的私有環境變數中，避免寫入原始碼與版本控制；停止使用後可直接撤銷。

### SSE 相容設定

部分 MCP 目錄僅提供 **SSE** 和 **stdio**。選擇 SSE 後填入以下設定，並在目錄的環境變數中新增私有變數 `TOKST_API_KEY`，其值為專用的 `tk_live_...` API 金鑰。

```json
{
  "mcpServers": {
    "tokst": {
      "type": "sse",
      "url": "https://api.tokst.com/sse?api_key=${TOKST_API_KEY}"
    }
  }
}
```

TokST 會透過 API 金鑰驗證 SSE 初始連線，隨後回傳短時工作階段端點處理 MCP 請求。支援 Streamable HTTP 的用戶端繼續使用 `/mcp`。

## 本地設定（適用於桌面智能體）

### Claude Desktop

加入你的 `claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "tokst": {
      "command": "bun",
      "args": ["x", "-y", "@tokst/mcp-server"]
    }
  }
}
```

### Cursor

加入專案根目錄的 `.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "tokst": {
      "command": "bun",
      "args": ["x", "-y", "@tokst/mcp-server"]
    }
  }
}
```

### Codex CLI

```toml
# ~/.codex/config.toml
[mcp_servers.tokst]
command = "bun"
args = ["x", "-y", "@tokst/mcp-server"]
```

雲端 MCP 使用瀏覽器授權或專用 API 金鑰；本機 MCP 使用 `tokst setup --local` 建立的私有 Local SQLite 設定。兩者均提供完整的 51 個工具，包括自動記憶狀態與路由設定；雲端另提供工作區治理、智能體協作、附件和帳戶操作。僅在需要聚焦的 11 個記憶工具時，為遠端服務設定 `TOKST_MCP_TOOLSET=core`。

## 工具參考

遠端 MCP 與本機 MCP 預設都提供管理、團隊和附件工具。`TOKST_MCP_TOOLSET=core` 會將遠端服務限制為 11 個核心記憶工具。

### 工作區治理工具

這些工具與後台使用相同的角色檢查。接受或拒絕邀請、撤銷邀請、離開、調整角色、移除成員、轉讓 Owner 均需要 `confirm: true`。

| 工具 | 用途 |
|---|---|
| `tokst_workspace_members` | 列出成員與角色 |
| `tokst_workspace_invitations` | 列出工作區已發邀請 |
| `tokst_workspace_invite` | 按角色和有效期發出一個或多個邀請 |
| `tokst_workspace_invitation_inbox` | 列出目前使用者的邀請 |
| `tokst_workspace_invitation_respond` | 接受或拒絕邀請 |
| `tokst_workspace_invitation_revoke` | 撤銷待處理邀請 |
| `tokst_workspace_leave` | 離開工作區 |
| `tokst_workspace_member_role` | 設定成員為 `admin` 或 `member` |
| `tokst_workspace_member_remove` | 移除成員 |
| `tokst_workspace_owner_transfer` | 將 Owner 轉讓給既有成員 |

### 記憶操作

#### `tokst_remember`

儲存新記憶，支援自動路由和向量嵌入生成。

| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `content` | string | 是 | 記憶內容 |
| `type` | string | 否 | `fact`、`decision`、`preference`、`task`、`architecture`、`note`（預設 `note`） |
| `tags` | string | 否 | 逗號分隔的標籤 |
| `source` | string | 否 | 來源名稱（預設 `mcp`） |
| `evidence` | string | 否 | 證據 URL 或來源檔案路徑 |
| `confidence` | number | 否 | `0` 到 `1` 的可信度 |
| `validUntil` | string | 否 | ISO 到期時間 |
| `atlasId` | string | 否 | 目標知識庫（省略時按關鍵詞自動路由） |
| `title` | string | 否 | 可選標題 |

#### `tokst_search`

與 CLI、REST 共用編排邏輯的自適應作用域搜尋。

| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `query` | string | 是 | 搜尋查詢 |
| `type` | string | 否 | 按類型篩選 |
| `tags` | string | 否 | 逗號分隔的標籤篩選 |
| `atlasId` | string | 否 | 限定知識庫 |
| `mode` | string | 否 | `auto`、`keyword`、`semantic` 或 `hybrid`（預設 `auto`） |
| `limit` | number | 否 | 最大結果數（預設 20） |

工具結果包含與 REST 一致的結果順序和 `meta` 耗時/快取欄位。

#### `tokst_context`

獲取按記憶類型分組的結構化上下文快照。

| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `atlasId` | string | 否 | 知識庫 ID（省略返回全部） |
| `limit` | number | 否 | 每類最大條數（預設 10） |

#### `tokst_memory_list`

列出最近的記憶。

| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `type` | string | 否 | 按類型篩選 |
| `atlasId` | string | 否 | 限定知識庫 |
| `limit` | number | 否 | 最大結果數（預設 20） |

#### `tokst_memory_get`

獲取單條記憶的完整詳情和附件。

| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `id` | string | 是 | 記憶 ID |

#### `tokst_memory_update`

替換記憶內容。

| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `id` | string | 是 | 記憶 ID |
| `content` | string | 是 | 新內容 |

#### `tokst_memory_append`

向已有記憶追加內容（自動加入 `\n\n` 分隔符）。

| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `id` | string | 是 | 記憶 ID |
| `content` | string | 是 | 追加內容 |

#### `tokst_memory_verify`

使用證據、可信度和可選有效期限驗證一條記憶。

| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `id` | string | 是 | 要驗證的記憶 ID |
| `evidence` | string | 否 | 證據 URL 或來源檔案路徑 |
| `confidence` | number | 否 | `0` 到 `1` 的可信度 |
| `validUntil` | string | 否 | ISO 到期時間 |

#### `tokst_memory_supersede`

將舊記憶標記為由同一知識庫中的新記憶取代。

| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `id` | string | 是 | 被取代的記憶 |
| `replacementMemoryId` | string | 是 | 新的替代記憶 |

#### `tokst_memory_archive`

歸檔記憶（軟刪除，可復原）。

| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `id` | string | 是 | 記憶 ID |

#### `tokst_memory_restore`

復原歸檔的記憶為活躍狀態。

| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `id` | string | 是 | 記憶 ID |

#### `tokst_memory_delete`

永久刪除記憶。

| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `id` | string | 是 | 記憶 ID |

#### `tokst_attach_file`

為已有記憶附加一個 ChatGPT 上傳檔案或遠端 URL。遠端伺服器下載檔案並上傳到 R2。

| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `memoryId` | string | 是 | 記憶 ID |
| `files` | array | 否 | ChatGPT 提供的檔案（`openai/fileParams`） |
| `fileUrl` | string | 否 | 通用 MCP 用戶端使用的可下載 URL |
| `filename` | string | 否 | 自訂檔案名稱 |

`files` 與 `fileUrl` 任選一個。遠端 MCP 單一檔案上限為 50 MB。

#### `tokst_download_file`

取得一條記憶中單一或全部附件的安全下載連結。連結有效期為 15 分鐘，同時以 MCP `resource_link` 回傳。

| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `memoryId` | string | 是 | 記憶 ID |
| `attachmentId` | string | 否 | 指定附件；省略時回傳全部附件 |

### 知識庫操作

#### `tokst_atlas_list`

列出所有知識庫。無需參數。

#### `tokst_atlas_init`

建立新知識庫。

| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `name` | string | 是 | 知識庫名稱 |
| `workspaceId` | string | 否 | 工作區（省略使用預設） |
| `keywords` | string | 否 | 逗號分隔的自動路由關鍵詞 |

#### `tokst_atlas_rename`

重新命名知識庫。

| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `atlasId` | string | 是 | 知識庫 ID |
| `name` | string | 是 | 新名稱 |

#### `tokst_atlas_profile`

設定知識庫的自動路由關鍵詞。

| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `atlasId` | string | 是 | 知識庫 ID |
| `keywords` | string | 是 | 逗號分隔的關鍵詞 |

#### `tokst_atlas_delete`

刪除知識庫及其所有記憶。

| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `atlasId` | string | 是 | 知識庫 ID |

### 工作區操作

#### `tokst_workspace_list`

列出所有工作區。無需參數。

#### `tokst_workspace_create`

建立新工作區。

雲端團隊工作區建立會使用帳戶的可用團隊工作區配額。本地 MCP 保留本地工作區模型。

| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `name` | string | 是 | 工作區名稱 |

#### `tokst_workspace_delete`

刪除空工作區。

| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `workspaceId` | string | 是 | 工作區 ID |

### 帳戶

#### `tokst_status`

取得帳戶概覽：方案、用量、儲存、工作區/知識庫數量。無需參數。

## 驗證

- **遠端**：`Authorization: Bearer tk_live_xxx` 標頭中的 API Key
- **本地**：讀取 `~/.tokst/config.json`（由 `tokst login --key <key>` 建立）

## 會話記憶協定

適用於多步驟任務與需要交接的工作。

```text
`tokst_session_start` — atlasId、task
`tokst_session_capture` — sessionId、kind、content、tags
`tokst_session_checkpoint` — sessionId、summary
`tokst_session_finalize` — sessionId、summary
`tokst_session_reopen` — sessionId（僅雲端/stdio ACP；保留同一條自動記憶）
`tokst_session_revert_automatic_memory` — sessionId、reason（僅雲端/stdio；封存自動記憶並保留稽核）
`tokst_session_status` — sessionId
`tokst_session_list` — workspaceId、scope、atlasId、status
`tokst_session_list_candidates` — workspaceId、scope、atlasId、status
`tokst_session_moderate_candidate` — sessionId、candidateId、action
`tokst_session_archive` — sessionId、archived
```

會話開始回傳範圍內上下文，候選內容保存已確認的長期資訊，會話結束寫入快照並預設編譯候選記憶。Owner 與 Admin 可治理工作區會話並撤銷已編譯候選。

完整智能體操作流程、交接規則、審核權限、本機一致性和重試行為請閱讀[工作階段記憶指南](/docs/sessions)。