Althea MCP

Althea MCP

让你的编码 Agent 直接联系你的 Althea。
共享研究记忆，以及由经验证的机器学习研究人员组成、以同意为先的网络。

让 Codex、Claude Code 和其他编码 Agent 直接联系你的个人 Althea。它们可以将问题、代码以及当前仓库中的上下文交给 Althea。Althea 会提供共享研究记忆；在有帮助时，还可以向由经验证的机器学习研究人员组成、以同意为先的网络寻求帮助。

• 让 Agent 彼此交流。 在你的编码 Agent 和 Althea 之间传递问题、代码、实验 结果和仓库上下文。
• 拥有自己的 Althea，并提供上下文。 MCP 使用你现有的帐户、个人资料 和长期研究记忆。
• 接入研究人员网络。 Althea 可以向经验证的机器学习研究人员寻求帮助；在分享 私密上下文前会征得同意。
• 按客户端区分对话。 为 Codex 和 Claude 指定不同的线程密钥后，两者的对话 将彼此分开，同时 Althea 会保留共享上下文。
• 异步工作。 等待回复、为较长的工作留言，或稍后阅读线程。

设置 · 连接客户端 · 开始首次对话 · 工具 · 安全与隐私 · 开发

设置

你需要能够访问 Althea，并安装 uv。 从 PyPI 安装 Althea MCP，然后使用通过电子邮件收到的验证码登录：

uv tool install althea-mcp
althea-mcp setup

如果安装成功但找不到命令，请运行 uv tool update-shell 并打开一个新终端。

请在交互式终端中自行运行设置。请在那里输入电子邮件地址和验证码，而不是在 AI 聊天中输入。

Connect your personal Althea
-----------------------------
Email: [email protected]
A verification code was sent to [email protected].
Verification code:

Althea MCP is ready.
Credentials saved to ~/.config/althea-mcp/credentials.json

设置流程与 Althea 网页应用中的帐户流程相同：

• 现有帐户会通过电子邮件收到验证码。
• 符合条件的新帐户会被要求提供姓名，然后收到验证码。
• 仍需申请访问权限的帐户会被引导至 Althea 应用。完成申请后，再次运行 设置。

安装后的服务启动时不会每次都获取代码。它的工具仍需连接网络才能访问 Althea。稍后可通过以下命令升级软件包：

uv tool upgrade althea-mcp

连接 MCP 客户端

完成一次设置后，添加本地 stdio 服务。为每个客户端使用不同的线程密钥。

注意

此服务可以读取 Althea 的私密历史记录并发送真实消息。仅在你信任的客户端和项目中注册它。

Codex

codex mcp add althea \
  --env ALTHEA_THREAD_KEY=codex \
  -- althea-mcp
codex mcp list

codex mcp add 会写入你的用户配置。等效的 ~/.codex/config.toml：

[mcp_servers.althea]
command = "althea-mcp"

[mcp_servers.althea.env]
ALTHEA_THREAD_KEY = "codex"

Claude Code

claude mcp add althea \
  -e ALTHEA_THREAD_KEY=claude-code \
  -- althea-mcp
claude mcp list

该命令使用 Claude Code 的项目本地作用域。只有当你希望在打开的每个项目中都能使用此服务时，才在 althea 前面立即添加 --scope user。

在 ~/.claude.json 顶层的 mcpServers 对象下，手动添加的全局配置如下：

{
  "mcpServers": {
    "althea": {
      "type": "stdio",
      "command": "althea-mcp",
      "env": {
        "ALTHEA_THREAD_KEY": "claude-code"
      }
    }
  }
}

Claude Desktop 和其他本地客户端

查找已安装的命令：

command -v althea-mcp

在 Windows PowerShell 中：

(Get-Command althea-mcp).Source

GUI 应用有时获取到的 PATH 比终端中的更短。如果找不到 althea-mcp，请使用上方返回的绝对路径：

{
  "mcpServers": {
    "althea": {
      "command": "/absolute/path/to/althea-mcp",
      "env": {
        "ALTHEA_THREAD_KEY": "claude-desktop"
      }
    }
  }
}

更改客户端的 MCP 配置后，请重启客户端。

开始对话

在 MCP 客户端中尝试以下任一提示词：

Ask my Althea whether anyone in the researcher network has worked on this
failure mode. Share only the sanitized summary below:
[summary]

Send this context to my Althea without waiting for a reply:
The latest experiment rules out the data-loader hypothesis. The remaining
failure starts after gradient accumulation.

Check whether my Althea has replied in the MCP thread.

消息会在已配置的对话线程中继续。这些消息会发送给你自己的 Althea，并可能促使她开始工作。

工具

工具	功能
ask_althea(message)	发送消息，默认使用 120 秒轮询窗口等待首条回复。若窗口超时，工作可能仍会继续。
send_message_to_althea(message)	立即发送消息并返回回执，不等待回复。适用于提供背景信息、备注和较长的请求。
get_althea_messages(sender=None, limit=10)	按时间顺序返回最近的 1 至 100 条消息。可按 user、assistant 或 system 进行筛选。
search_althea_conversations(query=None, limit=10)	按标题或主题搜索用户 Althea 账户中的对话。不指定查询时，返回最近的对话。
get_althea_conversation_log(conversation_id, limit=100)	按时间顺序返回任意所属对话中最近的 1 至 100 条消息，以及该对话的消息总数。

这两个发送工具会被标记为更改状态的工具。对话搜索和消息检索为只读操作。当前工具界面仅支持文本，不提供附件或其他 Althea 产物。

工作原理

Codex / Claude Code / another coding agent
                    │ local stdio
                    ▼
               Althea MCP
                    │ HTTPS
                    ▼
              your Althea
                    │
                    ├── your profile and long-term research memory
                    ├── a persisted conversation for this thread key
                    └── a consent-first network of verified ML researchers

Althea MCP 是一个小型公共适配器。前端负责验证用户身份、查找其对应的 Althea、发送消息，并存储由此产生的对话。调用方等待回复时，软件包会轮询已持久化的消息。编码 Agent 与 Althea 交流；如果请求适合借助外部专业知识，Althea 会与研究者网络协调。

登录和会话

安装会创建一个常规的 Althea 使用会话：

• 访问会话有效期为 7 天。
• 轮换刷新令牌系列自登录起有效期为 14 天。
• 访问令牌会在过期前自动刷新。
• 跨进程锁可让多个本地 MCP 客户端共用凭据文件，避免刷新令牌轮换时发生竞争。
• 会话过期或被撤销时，请在单独的终端中重新运行 althea-mcp setup。正在运行的 MCP 进程会重新加载替换后的凭据。
• 再次登录只会轮换凭据。如果 Althea 账户和 ALTHEA_THREAD_KEY 保持不变，对话历史不会被替换。

凭据以纯文本 JSON 格式存储在 ~/.config/althea-mcp/credentials.json 中。在支持 Unix 文件权限的操作系统上，凭据文件的权限会设为 0600。Althea MCP 创建的父目录会请求设为 0700；使用预先存在的自定义目录时，请自行检查权限。

安全与隐私

• 通过这些工具发送的消息会保存在你的 Althea 账户中，就像通过 Althea 其他渠道发送的消息一样。
• 本地 stdio 进程会通过 HTTPS 向 Althea 发送消息和凭据。即使使用本地传输，对话数据也会离开你的设备。
• 已连接的 MCP 主机和模型可以看到工具参数和回复。它们可能会根据自身的隐私和数据保留政策保留这些数据。
• 当 Althea 向研究人员网络寻求帮助时，她会在分享从私人对话中获取的信息前征求同意。
• 此软件包只会将访问凭据发送到签发凭据时对应的 Althea 源站。更改 ALTHEA_APP_URL 后需要重新设置。
• 刷新令牌只会发送到会话轮换端点。
• 邮件验证码和凭据文件均为机密信息。切勿将它们粘贴到 AI 聊天、终端记录、议题或拉取请求中。
• 如需移除本地会话，请关闭 MCP 客户端并删除凭据文件。这会清除该设备上的会话。如需同时撤销已复制的会话，请联系 Tiptree。

请通过安全政策报告漏洞。

配置

大多数用户只需运行 althea-mcp setup，并为每个客户端设置一个线程密钥。

环境变量	默认值	用途
ALTHEA_APP_URL	https://althea.tiptreesystems.com	Althea API 源站。已保存的凭据会与该地址绑定。仅在环回地址开发时接受普通 HTTP。
ALTHEA_PUBLIC_SITE_URL	https://tiptreesystems.com	条款、隐私和访问请求的基础 URL。Dev Althea 会自动选择 https://dev.tiptreesystems.com。
ALTHEA_THREAD_KEY	mcp	稳定的对话标识符。使用 1 到 128 个字母、数字、点、下划线、冒号或连字符，且必须以字母或数字开头。
ALTHEA_MCP_CREDENTIALS_FILE	~/.config/althea-mcp/credentials.json	覆盖本地凭据路径。
ALTHEA_MCP_HTTP_TIMEOUT	60	HTTP 超时时间，单位为秒。
ALTHEA_MCP_POLL_INTERVAL	2	轮询响应的间隔，单位为秒。
ALTHEA_MCP_POLL_TIMEOUT	120	ask_althea 的最长等待时间，单位为秒。
ALTHEA_MCP_LOG_LEVEL	WARNING	Python 日志级别。

设置时还可使用 --credentials-file 覆盖凭据路径，并使用 --no-browser 打印访问请求 URL，而不打开该 URL。

故障排查

Althea MCP is not configured

在终端中运行 althea-mcp setup，然后重启 MCP 客户端。

Your Althea MCP sign-in has expired or was revoked

重新运行设置。刷新令牌系列的绝对有效期为 14 天。

已保存的凭据绑定到了其他 URL

使用 MCP 客户端将使用的同一源站运行设置：

althea-mcp setup --app-url https://althea.example

然后在客户端配置中设置匹配的 ALTHEA_APP_URL。

ask_althea 超时

Althea 可能仍在处理。稍等片刻后调用 get_althea_messages。

客户端找不到 althea-mcp

在终端中运行 command -v althea-mcp，并在客户端配置中使用该命令返回的绝对路径。

两个客户端共用一个对话

为每个客户端分配不同的 ALTHEA_THREAD_KEY，然后重启客户端。

本地开发

git clone https://github.com/tiptreesystems/althea-mcp.git
cd althea-mcp
uv sync --locked --extra dev
uv run pytest -q
uv run ruff check althea_mcp tests
uv run ruff format --check .
uv build
uvx twine check dist/*

针对本地前端运行设置：

uv run althea-mcp setup --app-url http://localhost:8080

不带子命令运行 althea-mcp 会启动 stdio 服务。等效的显式命令是 althea-mcp serve。

贡献

欢迎提交 Bug 报告和内容聚焦的拉取请求。提交前请阅读 贡献指南。 请从日志和测试夹具中删除所有电子邮件地址、消息、OTP 和凭据。

许可证

MIT © Tiptree Advanced Systems Corporation。