# 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)。