跳转到主要内容

MCP 技术参考

当您需要传输详细信息、静态凭据、功能限制或协议故障排除时,请使用此页面。 将 Kanera 连接到您的 AI 代理.

连接方法​

连接认证有效获得
交互式OAuth浏览器登录并同意充当具有读写工具功能的连接用户。客户控制操作的可用性和批准; Kanera 强制执行用户的看板角色。它永远不会接收工作区管理访问权限。
设备授权在任何设备上的浏览器中批准的简短用户代码充当批准用户,与交互式 OAuth 完全相同。它永远不会接收工作区管理访问权限。
无人值守代理OAuth client_credentials使用工作区服务身份,其上限为管理员选择的最大读取、写入或管理权限。 管理员目前不会向默认 MCP 服务器添加任何工具;使用单独的工作区或板 API 密钥进行直接 REST 管理。
个人 API 密钥静态持有人令牌在可访问的板上充当其所有者。默认的 MCP 仍然以工作为中心;直接 REST 请求单独继承所有者支持的权限。
工作区或板 API 密钥静态持有人令牌保持固定到其标准工作区或独立板及其读取、写入或管理作用域。 管理员不会向默认 MCP 添加配置工具。

海 连接 AI 代理 交互式 OAuth、同意、撤销、无人值守代理和授权流程。

托管端点​

Kanera 托管的 MCP 端点是:

https://mcp.kanera.app/mcp

服务运行状况检查是:

https://mcp.kanera.app/health

支持 OAuth 的客户端可以直接添加 MCP 端点并在浏览器中完成身份验证。 使用 API 密钥的客户端将其作为载体令牌发送:

Authorization: Bearer kanera_live_...

如果您的团队在自己的地址运行Kanera,同样 /mcp 以及 /health 复制下面显示的确切 MCP 地址,然后将其复制到 配置文件设置 -> API 密钥 的那个Kanera。

协议版本​

托管端点从同一服务器同时服务于当前的 MCP 协议和 Claude、Codex、Cursor、Copilot、Gemini CLI 和 OpenCode 目前使用的早期版本。 旧客户端看到的工具、资源和提示与以前相同;使用当前协议的客户端也会看到 活动订阅。两者的工具模式都以相同的 JSON 模式方言发布,因此客户端不会看到不同的合约。 kanera mcp 对于 stdio 来说,它也同样接受这两种方式。

OAuth 令牌安全性​

支持 OAuth 的客户端会自动处理安全详细信息。 为 Kanera 连接发布的令牌仅适用于 Kanera 显示的 MCP 地址;不能将其重用作为一般公共 API 凭据。

如果您正在构建自定义 OAuth 客户端,请将该 MCP 地址作为 resource 下面的设备授权示例显示了它的所在位置。 对于直接调用 REST API 的集成,请使用个人、工作区或板 API 密钥。

针对 CLI 和无头客户端的设备授权​

无法接收浏览器重定向的客户端(例如终端工具、SSH 会话或没有可用浏览器的计算机)可以使用 OAuth 设备授权授予 (RFC 8628) 进行连接。客户端显示一个简短的代码,一个人在任何设备上的浏览器中批准它,然后客户端进行轮询,直到收到令牌。

结果是与交互式 OAuth 相同的身份。 该连接作为具有读写工具功能的批准用户,而 Kanera 继续在每个看板上强制执行该用户的角色,从不获得工作区管理访问权限。 批准设备请求需要允许代理连接的计划,这与任何其他代理连接的要求相同。

Kanera 流量的增加 /.well-known/oauth-authorization-server:

元数据字段价值
device_authorization_endpointhttps://api.kanera.app/oauth/device/code
grant_types_supported包括 urn:ietf:params:oauth:grant-type:device_code

注册设备客户端​

注册客户端 /oauth/register 仅设备客户端不需要重定向 URI; redirect_uris 只有当客户端也使用 authorization_code.

curl -X POST https://api.kanera.app/oauth/register \
-H 'content-type: application/json' \
-d '{
"client_name": "Acme CLI",
"grant_types": ["urn:ietf:params:oauth:grant-type:device_code", "refresh_token"]
}'

Kanera 会拒绝未注册设备授权类型的任何客户端的设备流。

请求设备代码​

curl -X POST https://api.kanera.app/oauth/device/code \
-d client_id=kanera_client_... \
-d resource=https://mcp.kanera.app/mcp \
-d 'scope=kanera:read kanera:write offline_access'

resource Kanera 将每个用户授权的设备请求正常化为一个 MCP 地址。 kanera:read kanera:write,包括省略的客户 scope 当客户端注册了该请求时,Kanera 会发出一个刷新令牌。 refresh_token 赠款类型; offline_access 接受但不要求。 仅 kanera:read, kanera:write, 和 offline_access 接受。

回应字段意义
device_code客户端在调查时发送回的秘密。
user_code人类型的短代码,格式如下 ABCD-2345.
verification_uri该 /oauth/device 您的Kanera网页地址页面。
verification_uri_complete查询字符串中预填充了代码的同一页面。
expires_in600。该请求在发出十分钟后就会过期。
interval5。轮询之间的最小秒数。

批准请求​

  1. 客户端显示的 user_code 与 verification_uri,或打开 verification_uri_complete 直接。
  2. 该人打开该地址并登录到 Kanera(如果他们尚未登录 ) 。
  3. 该页面给客户端命名,显示代码以便与终端进行对比,并列出客户端将能够执行的操作。
  4. 选择 允许访问 批准连接。 选择 否定 拒绝了。

令牌的投票​

curl -X POST https://api.kanera.app/oauth/token \
-d grant_type=urn:ietf:params:oauth:grant-type:device_code \
-d device_code=kanera_device_... \
-d client_id=kanera_client_... \
-d resource=https://mcp.kanera.app/mcp

投票不快于 interval。直到请求完成,令牌端点返回 400 标准的OAuth错误:

错误意义客户应该做什么
authorization_pending尚未有人批准或拒绝该请求。保持在当前间隔进行调用。
slow_down客户端的调查速度快于间隔。Kanera 将增加5秒的间隔时间,从现在开始使用更长的间隔时间。
access_denied该人拒绝了这一要求。停止调查并启动新请求。
expired_token代码过期,或其令牌已发出。开始一个新的请求。
invalid_grant设备代码未知或属于另一个客户端。开始一个新的请求。

批准后,端点返回与其他每个授权相同的有效负载:受众绑定 kanera_mcp_... 访问令牌有效期为15分钟,客户端注册时会有一个刷新令牌。 refresh_token 设备代码是一次性使用的,因此重复交换返回 expired_token。刷新请求必须包含相同的内容 resource.

管理或撤销设备连接,在此处管理每个其他代理连接, 配置文件设置 -> API 密钥.

创建 API 密钥​

使用 API 密钥来支持本地 stdio、仅接受静态载体令牌的客户端或自定义服务器端集成。

个人 API 密钥​

  1. 开放 配置文件设置.
  2. 去看看 API 键.
  3. 创建个人 API 密钥。
  4. 选择 只读 或 阅读和写作。对于无人值守的代理来说,只读是正确的默认设置:Kanera 拒绝 API 上的每个突变,因此客户端的工具权限并不是代理和您的工作之间的唯一障碍。与只读密钥连接的客户端仅获得读取工具,因此它永远不会计划无法进行的更改。
  5. 添加一个可选的私人标签来识别客户。
  6. 当它显示时,复制密码。

个人密钥有一个前缀,例如 kanera_u_live_...。它显示一次并充当其所有者,受您选择的范围限制。仅将其存储在 AI 客户端的凭证存储或服务器的秘密管理器中。

工作区或板 API 密钥​

  1. 打开标准工作区或独立看板。
  2. 去看看 设置 -> API.
  3. 创建 API 密钥。
  4. 选择适合工作流程的最小范围。
  5. 当它显示时,复制密码。

用于管理作用域密钥和无人值守代理的 Workspace API 设置。

范围赠款
阅读检查、搜索、总结和报告,而不需要更改 Kanera。
写创建和更新白板内容,包括卡片、清单、评论、任务、标签、自定义字段值和注释。
管理员执行支持的直接公共 API 管理。 默认 MCP 服务器保持工作重点,不会公开任何工作区、板、列表、标签、字段、选项、保留或订单管理工具。

连接本地 stdio 客户端​

下面是最简单的本地 stdio 服务器: Kanera CLI。安装它,登录一次,然后将客户端指向 kanera mcp;它使用存储的凭据在 stdio 上提供相同的工具层,因此无需在第二个位置配置第二个密钥。

npm install --global @kanera/cli
kanera auth login
{
"mcpServers": {
"kanera": {
"command": "kanera",
"args": ["mcp"]
}
}
}

使用 npx @kanera/cli mcp 当你不想安装任何东西时,请使用全局安装,并添加 "args": ["mcp", "--profile", "agent"] 选择一个命名的配置文件。

要通过环境而不是存储的配置文件(CI 或沙盒代理中的通常选择)提供凭据,CLI 和独立 MCP 包都会显示:

环境变量目 的
KANERA_API_KEY个人、工作区或板 API 密钥。
KANERA_PUBLIC_API_URLKanera 公共 API 源,如 https://api.kanera.app.
{
"mcpServers": {
"kanera": {
"command": "npx",
"args": ["-y", "@kanera/cli", "mcp"],
"env": {
"KANERA_API_KEY": "kanera_u_live_...",
"KANERA_PUBLIC_API_URL": "https://api.kanera.app"
}
}
}
}

当您根本不需要在本地运行 MCP 进程时,请使用托管 HTTP 端点。

资源​

Kanera 提供四种结构化 JSON 资源模板:

资源URI含有
标准工作区kanera://workspace/{workspaceId}凭证可见的有界工作区配置和共享列表、标签、字段、模板、自动化和成员资格
看板kanera://board/{boardId}标准工作区或独立板的有界元数据和可见配置,无卡
卡片kanera://card/{cardId}卡片详细信息,包括标签、受让人、清单、附件和链接注释
备注kanera://note/{noteId}可见的个人或团队笔记

个人笔记对于已连接用户是私密的,不要暗示其他工作区成员或工作区服务凭据可以阅读它们。

卡片参考​

命名的 MCP 卡字段 cardId 或 cardIds 接受以下任何参考:

  • 人类卡片钥匙,例如 PROJ-123,包括使用先前工作区前缀的精确键。
  • 规范的 Kanera 卡 URL。
  • 公共 API 返回的卡片 UUID。

在提示和面向用户的回复中使用人类密钥。 Kanera 会在调用现有公共 API 操作之前将其解析为 UUID,因此授权、Activity 和审核行为保持不变。 解析后的密钥会在连接中保存几分钟,因此在多步任务中重复使用该密钥不会重复查找。

卡结果包括当前人类可读的密钥。的 kanera://card/{cardId} 资源 URI 继续使用 UUID;人类键和链接适用于 MCP 工具输入。

能力组​

实时工具模式是名称、输入、安全注释和限制的权威。 服务器目前涵盖:

面积可用操作
发现检查代理会话、页面标准工作区和可访问的看板、读取限制工作区或看板配置以及页面看板和成员
配置边界读取目标工作所需的列表、标签、字段、选项、成员和权限。 创建、编辑、重新排序、保留和其他列表/工作区管理操作仍保留在 Kanera 界面中,而不是 MCP 工具
搜索搜索实时卡片、笔记、评论和附件文件名,或搜索官方的 Kanera 文档
卡片阅读摘要或完整内容,为多达 200 张选定卡片检索限制清单/注释内容,创建、更新、移动、重新排序、复制、在兼容板之间移动,存档、解除存档、完成、重新打开和管理附件和封面
卡牌关系用以下方法读取单个链接 cards.get,探索链 cards.dependency_graph,并添加或删除 blocks, blocked_by, 或 relates_to 与 cards.set_relations
附件使用 cards.get_attachment (图像作为图像,文本文件作为分页文本);从代理自己的磁盘附加一个文件 cards.create_upload_link,它返回代理上传到的一次性 URL curl -T
板隔板创建标题、可选颜色分隔符;更新其外观;相对于卡片、分隔符或列表边缘移动它们;相对于分隔符放置卡片;删除分隔符而不更改卡片
批量卡工作在选定的卡片上完成、日期、标签、分配、移动、存档、复制或设置自定义字段,并在每个方案中公开板级批量限制
作业和字段替换分配者或标签,并设置或清除支持的自定义字段值
评论意见页面,添加可选附件,编辑,删除合格的评论,并同时添加或删除反应
检查清单将卡片的清单作为嵌套树读取,并附带 ID;在一个原子调用中创建一个清单,其中包括项目、分配人、到期日期和一个级别的子清单;在选定位置添加一个或多个项目;更新一个或多个项目,每个项目有不同的更改;为每个项目设置一个分配人或到期日期;重命名、重新排序、移动和删除。
下一个优先事项发现可读的个人和团队队列,读取确切的排名顺序,并在凭据和工作区权限允许时添加、移动或删除分配的活动卡片
代理运行在卡片上宣布飞行中的工作 runs.start,报告进度和心跳 runs.update,以终端状态关闭运行,并检查已经运行的内容 runs.list
工作和报告查询带有逾期、未分配、不活动和最后移动过滤器的限制个人或可见团队卡片;通过 work.my_day;检查时间线计划和跨板汇总 work.portfolio_summary;并在可访问的板上生成个人站立证据
活动和完成的工作页面板活动和卡片历史记录,并阅读完成历史记录和工作完成记录
笔记页面笔记元数据,阅读完整内容,创建、更新、链接、附加小文件,复制和重新排序个人或团队笔记
便笺将“提醒我……”项目捕获到您的私人空间 便笺 无需选择论坛即可查看收件箱,列出和阅读页面,并勾选项目。 需要浏览器登录或个人密钥

见下文第10段。 生成 MCP 工具库存 对于每个注册的工具名称。

卡牌关系​

cards.get 包括卡的 relations 以及 hiddenBlockerCount. cards.set_relations 添加或删除同一工作区中的关系:

{
"cardId": "WEB-18",
"direction": "blocked_by",
"otherCardIds": ["MKT-42", "MKT-43"],
"remove": false
}

direction 是 blocks, blocked_by, 或 relates_to, 读取自 cardId的一边。 otherCardIds 接受一张或多达50张卡片参考; remove 添加是同权的,并且按目标提交。 部分成功返回 failed 条目和任何 notAttemptedCardIds 如果最终读取失败,则返回原始数据。 addedCardIds 以及 relationsUnavailable 当每次尝试更改都被拒绝时,调用会出错。 删除提交也会按照目标进行: removedCardIds 保留成功的移除与任何 failed, notAttemptedCardIds, 或 relationsUnavailable 详情。 notFoundCardIds 命名它无法看到或找到的关系;这些关系将被单独留下。

可写入的凭证需要编辑访问权限 cardId 读取会删除无法访问的卡片详细信息,但会计算隐藏的活动卡片。 使用 读取会删除无法访问的卡片详细信息,但会计算隐藏的活动卡片。 filters: { blockedOnly: true } 与 work.query_cards 对于被封闭的公开牌,或 atRiskOnly: true 对于其可见的阻止器已过期或到期后的开放卡; work.portfolio_summary 订阅我们的新闻通讯 card.blocked 以及 card.unblocked 这些事件独立于配置的自动化进行工作。

通过 MCP 完成操作不会显示交互式的工作受阻警告。判断工作是否已就绪时,应先读取关联关系。处于受阻状态的代理运行(runs.update 与 status: "blocked")描述了运行并且不会创建卡依赖性。参见 卡片关系与阻塞.

依赖图​

cards.dependency_graph 说明哪些工作阻塞了卡片、卡片阻塞了哪些工作,以及看板或工作区内有哪些相关工作。以下参数必须且只能传入一个: cardId (密钥、UUID 或规范 URL), boardId, 或 workspaceId:

{ "cardId": "MKT-42" }

工具返回扩展 cards, edges, 和 truncated。卡片包括其密钥、标题、URL、来源板/列表名称、 inScope,以及可用日期、标签和受让人。 openBlockerCount 包括呼叫者看不到的活动阻止器; offMapBlockerCount 计算此映射中缺少的活动阻塞器。 仅包含现有非零可选值。 A blocks 边缘运行从 sourceCardId 至 targetCardId.

卡范围也返回 focus: blockedBy 以及 blocks 是直接连接; upstream 以及 downstream 是最接近第一序列的可传递卡片 ID; relatedTo 列出上下文链接。 onMap: false 表示请求的卡片已完成、存档、无关联或以其他方式从图中缺失。 缺失并不证明卡片没有关系。

图形跟随可读的开放卡片的双向阻塞链接。 完成的先决条件可以出现,但不会通过它们继续穿越。 隐藏的卡片被计数,但不被命名或用于连接到其他工作。 truncated;缩小范围以获得更多细节。这是一个阅读工具。使用 cards.set_relations 编辑链接和 依赖事件 监控变化。

日期​

日期输入接受 YYYY-MM-DD 或者日常短语,在您自己的时区从您的Kanera配置文件解决: today, tomorrow 1pm, friday (下周五,包括今天), next friday (一周后), in 2 weeks, next month, end of week, end of month, 或 oct 12. session.get 返回你的 timeZone 以及 today Kanera 的到期日使用时间间隔而不是确切的时间,所以时间会选择匹配的时间间隔: 到 09:00 是 12:00, 13:00 是 16:00, 17:00 是 20:00, 21:00 是 22:00, 23:00 是 24:00。 上午,截至 13:00 下午,截至 17:00 工作日结束,以及之后的全天时段。无法读取的短语 Kanera 会被接受的形式拒绝,而不是猜测。

结果顺序​

每个列表工具的描述都会说明其结果的显示顺序,例如对于评论和活动来说是"最新的先显示 ", 对于列表和清单来说是显示顺序,对于 work.query_cards 默认情况下。

时间表和开始日期​

使用 work.schedule 与正好一个 boardId 或 workspaceId。它读取与相同的工作日引擎 时间轴视图,遵循跨棋盘可访问的连接链,并排除已完成和不可访问的卡。显示过滤器不会改变计算。

结果意义
cards[].plannedStart, plannedEnd, durationDays计划的日期范围及其周一至周五的持续时间。
earliestStart, earliestFinish, latestStart, latestFinish受依赖关系约束的日期和保留链结束的最后日期。
slackDays, critical工作日的延迟空间,以及连接的工作是否没有延迟。 零延迟意味着计算没有日期锚点。
conflicts[]冲突的开放阻塞器,与 blockerId, edgeId, kind,以及工作日 days.
criticalEdgeIds调度关键路径上的关系。
summary排定/未排定、冲突和临界点数、日期范围、 projectedFinish, latestDue,以及工作日 slipDays 对照最后到期日。

通过 startDateLocalDate 至 cards.create, cards.update 内部 changes,或每个条目 cards.bulk_create。使用 YYYY-MM-DD 或在用户区域中解析的支持的相对日期短语; null 清除现有开始。 开始没有时间间隔,不能超过到期日期。 这些写入需要编辑权限,并且不会自动移动继任日期。

没有假设的时间表输入:从当前时间表提出更改,然后仅在打算保存更改时应用并重新读取。 参见 工作规划示例 以及 调度事件有效载荷。禁用规划功能回归 TIMELINE_DISABLED 或 DEPENDENCIES_DISABLED 对于需要它们的操作。

活动订阅​

当前MCP协议上的客户端可以订阅 card.created, card.updated, card.moved, 和 comment.created 工作区、板或卡片中,以便 priorities.changed 下一队列,并将其添加到已连接用户的下一队列中。 my_day.ready 订阅属于连接,每次刷新持续时间最长为 24 小时,并且在每次交付之前都会根据身份的当前访问权限重新检查。 参见 订阅事件 用于目录、验证、签名、重试和错误代码。

内置提示​

提示符使用
summarize_board_status检查一个看板并总结进度、阻碍因素、陈旧工作和下一步行动。
prepare_standup_update将个人当前工作和分页工作历史记录结合在无障碍板上,以草拟一份立场文件。
draft_card_from_notes阅读笔记并草拟卡片标题和 Markdown 描述,而无需创建卡片。

即使 AI 客户端不公开 MCP 提示模板,正常的对话提示也会正常工作。

安全和破坏性行动​

  • 交互式和设备代码 OAuth 始终授权 kanera:read 以及 kanera:write; offline_access MCP 客户端控制工具的可用性和审批,而 Kanera 则强制执行板角色。 管理工具仅在用户拥有相应的管理员角色时才能运行:组织管理员可以创建工作区和独立板,工作区管理员可以添加板和管理自动化。
  • 每个 OAuth 流都将其授权、代码、刷新系列和访问令牌绑定到规范 MCP resource.
  • 原始 kanera_mcp_... 访问令牌仅被 MCP 端点接受,并被 /api/v1; MCP 服务对公共 API 调用使用单独的分钟生存期内部委派凭证。
  • 设备授权使用相同的范围和限制,设备代码在 10 分钟后过期,可交换一次,并且只有登录用户确认客户端显示的代码才能批准。
  • 无人值守代理和工作区密钥的上限为其配置的作用域。
  • 私钥继承其所有者的当前权限,并且应该像用户帐户一样受到保护。
  • 读取作用域 API 密钥和无人值守服务凭据不能调用受保护的变异。
  • API-key 和 MCP 活动与其代理用户或集成身份一起记录。交互式 OAuth 代理被记录为代表其用户的代理:注释和活动行携带代理的名称并呈现为 via <agent>,并且用户会收到关于他们的代理做了什么的通知,而不是将其作为自己的操作进行抑制。脚本使用的个人 API 密钥仍充当其所有者。
  • 断开 OAuth 连接或删除无人值守代理将撤销其活动凭据。
  • 每个客户端使用单独的凭据,以便在撤销一个连接时不影响另一个连接。

Kanera MCP 无法删除:

  • 看板
  • 列表
  • 标签或自定义字段
  • 笔记
  • 附录

删除那些手动 Kanera. MCP 可以存档或取消存档卡片,并且可以存档列表中的活动卡片。

MCP 的管理仅限于创建工作区和独立板(组织管理员,使用交互式 OAuth 授权或可写入的个人密钥)、向工作区添加板以及创建、编辑、启用和删除自动化(工作区管理员)。 MCP 无法编辑、重新排序或删除工作区、看板、列表、标签、字段、选项、成员或保留设置。这些操作仍保留在 Kanera 界面中;支持的 REST 端点仍然可用于有意构建的集成。

MCP 可以永久删除:

  • 由代理用户撰写的评论
  • 清单及其项目
  • 清单项目

这些工具模式被标记为破坏性的,只有在明确请求后才使用,并且在调用之前验证目标。

故障排除​

问题要检查什么
客户端无法连接使用精确的 /mcp 您正在连接的 Kanera 的 URL,如下所示 配置文件设置 -> API 密钥.
客户端请求令牌而不是打开 Kanera它不支持远程 MCP OAuth。 请使用 API 密钥或受支持的客户端。
您的浏览器没有自动跳转,请点击这里使用 设备授权 如果客户端支持,则提供一个 API 密钥。
投票不断回来 slow_down比较快的调查 interval 返回的设备代码,并在每个 slow_down.
设备页面报告无效或过期代码代码有效期为 10 分钟,只能使用一次。 检查代码,先登录,然后向客户端请求新代码。
标记端点返回 invalid_target从哪里发送确切的 MCP 地址 配置文件设置 -> API 密钥 作为 resource 在授权和每次令牌交换期间。
报告缺少 API 密钥集合 KANERA_API_KEY 为 stdio 或发送 Authorization: Bearer ... 通过 HTTP 传输。
请求返回 401凭据丢失、形式不正确、过期、已撤销或复制不正确。 重新启动 OAuth 或更换 API 密钥。
请求返回 403对于个人 OAuth,请确认代理用户是目标板上的编辑者而非观察者。 对于 API 密钥或无人值守代理,还请确认凭据具有写入功能。
代理可以读取但不能编辑允许 MCP 客户端中的写入操作,并确认代理身份具有板编辑器访问权限。对于服务连接和 API 密钥,还可以使用可写入的凭据。现有个人 OAuth 连接不需要重新连接。
代理无法找到一个板看板可能是独立的,也可能仅通过明确的访客会员身份才可访问。
代理无法管理工作区MCP 仅涵盖创建工作区和看板以及管理自动化,并且仅适用于代理身份为管理员的情况;工作区范围和只读凭据无法创建工作区。 对于其他管理,请使用 Kanera 接口或支持的公共 REST 端点。
编码代理有工具,但使用它们很差安装官方 Kanera 特工技能.
新工具或更改的工具不会显示刷新或重新扫描客户端中的 MCP 服务器,以便其检索当前的架构。 如果客户端没有刷新操作,请重新启动客户端;通常不需要 OAuth 重新授权。
客户端无法订阅事件需要帮助的朋友 /mcp 一个客户端和一个服务器,在当前的MCP协议上; kanera mcp 服务器从不提供它们。 订阅事件 回调和作用域错误。