alt
开发者文档

开发者文档

MCP

将 Claude、Codex 等 MCP 客户端连接到你的 Alt 笔记。

Alt 提供托管的 MCP（Model Context Protocol） 服务器。支持 OAuth 的客户端可通过浏览器登录连接，API 密钥仍可作为备用方式。两种方式都应用相同的只读 scope 和 workspace 边界。

从这里开始

在项目目录中运行交互式设置向导。它会依次引导你连接 MCP、验证 API 密钥和 Webhook，并将实现工作交给编码智能体。

npx
npx altalt --mcp-only

1. 使用 OAuth 连接（推荐）

只添加端点，不添加 header。客户端会发现 Alt 授权服务器、自动注册，并打开浏览器同意页面。

  • Alt 支持 Dynamic Client Registration 和 PKCE，因此兼容客户端会自动配置 OAuth。
  • 批准访问前，请在浏览器中检查请求的只读 scope 和 workspace。
  • OAuth 目前仅限 Alt 管理员使用。如果升级后旧的 Alt OAuth 连接无法认证，请从客户端删除并重新添加一次。

2. 连接客户端

OAuth 请使用仅包含 URL 的配置。无需 OAuth client ID 或 secret；只有客户端无法完成 OAuth 时才使用 API 密钥。

MCP URL
https://mcp.altalt.io/mcp

Claude / Claude Desktop / Cowork

打开 Customize → Connectors → Add custom connector，输入上方端点，OAuth client ID 和 secret 留空，然后选择 Connect。

Claude Code

shell
claude mcp add --transport http alt https://mcp.altalt.io/mcp

添加服务器后，在 Claude Code 中打开 /mcp，选择 Alt 并完成浏览器认证。

Codex CLI

shell
codex mcp add alt --url https://mcp.altalt.io/mcp
codex mcp login alt
config.toml
# ~/.codex/config.toml
[mcp_servers.alt]
url = "https://mcp.altalt.io/mcp"

添加服务器通常会同时完成浏览器认证。如果认证没有开始，请运行 codex mcp login alt。

Cursor

添加到 Cursor

仅注册 URL 的一键安装。在 Cursor 的 MCP 设置中选择 Connect 或 Needs authentication，并在浏览器同意页面批准。

其他客户端与 API 密钥备用方式

请先使用仅包含 URL 的 OAuth 配置。如果客户端不支持 MCP OAuth，再使用 Bearer API 密钥配置。

OAuth
{
  "mcpServers": {
    "alt": {
      "url": "https://mcp.altalt.io/mcp"
    }
  }
}
API 密钥
{
  "mcpServers": {
    "alt": {
      "url": "https://mcp.altalt.io/mcp",
      "headers": { "Authorization": "Bearer alt_live_..." }
    }
  }
}

自动化和旧客户端仍可使用 API 密钥。请在账户控制台创建密钥，只授予所需 scope，不要写入共享配置，并参阅安全了解密钥管理。

3. 工具

四个只读工具,与 REST API 一一对应,并检查相同的 scope。

  • list_notes — 列出密钥可见的笔记 — 支持游标分页和 updated_after 过滤(notes:read)。
  • get_note — 获取单条笔记的元数据: 标题、转写/摘要就绪状态、时间戳(notes:read)。
  • get_note_transcript — 以带时间戳和说话人标签的分段获取完整转写(transcripts:read)。
  • get_note_summary — 以 Markdown 获取 AI 摘要(summaries:read)。

笔记会在录音结束或摘要生成后出现 — 仅有备忘的笔记不会导出。内容就绪前工具会返回 transcript_not_ready / summary_not_ready,代理可以稍后重试。