MCP 接入

把账本接入外部 AI 客户端；需要生成令牌、选择权限和复制配置时使用本页。

Calends 内置一个 MCP 服务器。接入后，Claude Code、Codex、Cursor 等 AI 助手可以直接查询和修改你的账本：「下周有什么要续费？」「Netflix 从今天起涨到 17.99 美元。」

端点

https://calends.example.com/mcp

/mcp 只用于 MCP 服务请求。浏览器打开该地址会跳转到 AI 接入与 MCP 连接页 /connect；未登录时会先进入 /login?next=...，登录后返回连接页。

传输方式：Streamable HTTP 的无状态模式。每个 POST 是一条（或一批）JSON-RPC 请求，直接返回 JSON；不开 SSE 推送流，不保留会话。
鉴权：请求头 Authorization: Bearer <令牌>。
支持的协议版本：2025-06-18、2025-03-26、2024-11-05。

生成令牌

打开侧边栏的「连接」（/connect），点「新建令牌」。
填名称（给哪个 AI 用），选权限：
- 读写：可以查询，也可以新增和修改订阅、扣款与收款；
- 只读：只能查询，不能修改任何数据。
点「生成」。令牌以 sub_ 开头，只在生成时返回。当前页会暂存它以填入客户端配置，刷新后无法再次读取；丢失后点「吊销」并重新生成。

建议每个助手用一个单独的令牌，需要时可以单独吊销。令牌列表显示名称、权限、开头几位、创建时间和最近使用时间。服务端只保存令牌的 SHA-256。

只读令牌在 tools/list 里只能看到读取类工具；用它调用写入类工具会返回错误。

配置客户端

「连接」页为以下八种接入方式提供配置。刚生成的令牌会填入当前页的配置，刷新后不能再读取。点「只复制配置」，或把页面生成的提示词交给对应助手；复制内容可能包含令牌。

在终端运行，将 <令牌> 替换为刚生成的令牌：

claude mcp add --transport http calends https://calends.example.com/mcp \
  --header "Authorization: Bearer <令牌>"

在终端设置令牌环境变量，再注册服务器。启动 Codex 的进程也必须能读取该变量。

export CALENDS_TOKEN='<令牌>'
codex mcp add calends --url https://calends.example.com/mcp --bearer-token-env-var CALENDS_TOKEN

合并到 ~/.cursor/mcp.json。刚生成令牌时，「连接」页也提供「添加到 Cursor」。

{
  "mcpServers": {
    "calends": {
      "url": "https://calends.example.com/mcp",
      "headers": { "Authorization": "Bearer <令牌>" }
    }
  }
}

合并到 claude_desktop_config.json，通过 mcp-remote 连接。电脑需要能运行 npx。

{
  "mcpServers": {
    "calends": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://calends.example.com/mcp", "--header", "Authorization: Bearer <令牌>"]
    }
  }
}

在终端运行：

gemini mcp add --transport http calends https://calends.example.com/mcp \
  --header "Authorization: Bearer <令牌>"

在 Grok Bot 打开「设置 → Plugins」，添加 MCP 服务器。

按下面填写名称、地址和请求头：

name: calends
url: https://calends.example.com/mcp
headers:
  Authorization: Bearer <令牌>

保存后，让 Grok Bot 查询在用的订阅。

本接入标为「实验性」。将下面内容合并到 ~/.dsh/profiles/web/cordis.patch.yml：

- insert:
    - id: mcp-calends
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: calends
        transport: streamable-http
        url: https://calends.example.com/mcp
        headers:
          Authorization: 'Bearer <令牌>'

它是外部 MCP 客户端，与 Calends 的内置 DeepSeek 助手分别配置。

界面中叫「其他」。任何支持 Streamable HTTP 的 MCP 客户端都可连接。可先发送一条读取工具列表的请求：

POST https://calends.example.com/mcp
Authorization: Bearer <令牌>
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/list"}

配置完成后，让助手调用 get_overview，核对今天、本位币和在用订阅数。本文配置对应 Calends「连接」页生成的内容；客户端升级后，以客户端接受的格式为准。

写入前先预览

所有写入类工具都支持 dry_run：传 true 时只返回预览，不保存。MCP 不强制草稿确认流程；读写令牌在未传 dry_run 或传 false 时会直接修改账本。删除订阅这类不可逆的操作，工具说明里要求助手先预览、由你确认。

每个工具都带有 MCP 注解：读取类标记为只读，删除类标记为破坏性操作，支持的客户端会据此决定是否需要你确认。

工具的完整列表见 MCP 工具参考。

总开关

「设置 → 开放 → AI 连接（MCP）」，或「连接」页顶部的开关。关闭后：

/mcp 拒绝所有请求（HTTP 403），已发出的令牌全部暂时失效；
侧边栏里的「连接」不再显示。

重新打开后，原来的令牌恢复可用。这个开关不影响内置助手。