Gagarin Cloud

mcp

mcp.gagarin.cloud — 轻松部署，维护无忧。

只需向 Agent 添加一个 URL，它就能在可访问的 HTTPS 地址运行你的应用，为其配置 Postgres、Qdrant、Valkey、队列或存储桶，设置哪些服务可以互相访问，并回滚。警报、日志、备份和项目记忆也一并提供，而且未经你的邮件批准，不会删除任何内容。这是 Gagarin 的 API，以工具的形式提供：共 51 个，每个工具都附有注释，让客户端知道该先向你询问哪个工具。构建并推送镜像需要 docker 和源代码，因此这一步需要在拥有它们的机器上执行 gg ship；之后的一切都在这里完成。

https://mcp.gagarin.cloud/mcp

模型上下文协议（Model Context Protocol）让 Agent 能够发现并调用它原本未内置的工具。这就是 Gagarin 的 MCP 服务，其存在的目的，是让你只需提供一个 URL，而不是安装程序，就能将 Gagarin 添加到编码 Agent 中——正是这个要素让平台变得可安装，而不只是有文档说明。

两种接入方式，同一套实现：

远程	https://mcp.gagarin.cloud/mcp，可流式传输的 HTTP，通过 Authorization 标头传递凭证——可由 OAuth 登录自动填写，也可手动填写
本地	克隆此仓库后运行 npm run stdio，凭证来自 GAGARIN_TOKEN 或 gg login 写入的文件——用于在此服务上进行开发，并非安装方式

登录

远程，通过 OAuth 登录。 只需向客户端提供 URL，无需其他内容：

https://mcp.gagarin.cloud/mcp

Claude、ChatGPT 和 Claude Code 在连接时会提示登录：客户端会打开浏览器，用户使用 GitHub 或 Google 登录。未提供凭证的请求会收到 401 响应，其中的 WWW-Authenticate 标头指向 /.well-known/oauth-protected-resource/mcp，该地址将 api.gagarin.cloud 指定为授权服务器。此服务本身不会对令牌做任何判断；每次调用时都由引擎进行判断。开发环境可通过 GAGARIN_MCP_ORIGIN 和 GAGARIN_ISSUER 覆盖这两个公开名称；它们与 GAGARIN_API 相互独立，后者在集群中是集群内的 Service，并不是客户端可以登录的地址。

远程，通过标头传递凭证。 适用于无法通过 OAuth 登录的客户端，或不应登录的机器：凭证来自 gg login 或 gg creds create。

{
  "mcpServers": {
    "gagarin": {
      "type": "http",
      "url": "https://mcp.gagarin.cloud/mcp",
      "headers": { "Authorization": "Bearer <your gagarin credential>" }
    }
  }
}

本地，通过 stdio。 克隆仓库后运行 npm run stdio，即可通过管道运行同一套工具；它会读取 gg login 写入的文件，或者在设置了 GAGARIN_TOKEN 时使用该变量。此方式用于开发，刻意不发布到 npm：此 MCP 服务的目的，是让你只需提供 URL，而不是安装程序，就能将 Gagarin 添加到 Agent；而某人笔记本电脑上的软件包，不过是 src/tools.ts 的另一个副本，在工具变更的那一天就会过时。

过期或已撤销的凭证也会在入口处被拦截，因为客户端只有收到 HTTP 401 才会重新登录：每个 POST 请求都会先使用调用者的令牌向引擎请求 /v1/whoami，引擎返回的 401 会转为包含 error="invalid_token" 的 401。每个请求会额外进行一次集群内调用，且不设缓存——记住的令牌就是存储的令牌，而此服务不存储任何令牌。其他任何失败（引擎无法访问、返回 5xx）都不属于登录问题，因此请求会继续处理，每个工具都会使用引擎自身的代码报告错误。

开发

npm install
npm run build
npm test                 # builds, then node --test over dist/
npm start                # the HTTP server on :8080
npm run stdio            # the same tools over a pipe

内容概览

路径	说明
src/api.ts	此服务与 Gagarin 的所有交互：一次请求，一个错误封装
src/tools.ts	所有工具——每个工具都包含一个路径、一种结构，以及调用者使用前需要了解的规则
src/server.ts	客户端连接时会收到的内容，以及 gagarin://guide 资源——包括如何使用记忆，以及说明仓库所属项目的 .gagarin.json 注释
src/app.ts	mcp.gagarin.cloud：无状态的可流式传输 HTTP、每个请求创建一个服务，以及 OAuth 受保护资源元数据
src/http.ts	监听器、其配置及其排空流程
src/stdio.ts	通过管道提供相同的工具，用于基于克隆版本进行开发
src/credentials.ts	读取 gg login 写入的凭据文件；不会写入任何文件
Dockerfile	mcp.gagarin.cloud 运行所用的镜像。其构建阶段会运行测试

项目记忆

每个项目都带有记忆：Agent 保存的少量、持久的代码库事实——一项决策及其原因、一种惯例或一个易踩的坑——让下一个会话无需重新发现这些内容。它是项目的内置功能，就像项目的注册表一样，并且只有通过这些工具才能访问它：记忆服务没有自己的地址、没有 gg 命令，也没有控制台页面。引擎会像处理其他所有内容一样，在每次调用时决定谁可以读取（查看者），谁可以写入（编辑者）。

工具	功能
memory_briefing	将项目已知信息压缩到令牌预算内——用于项目上的首次调用；focus 和 paths 可调整内容，并以最近 7 天的变更收尾
memory_search	混合语义搜索与关键词搜索；不提供查询时按排名浏览
memory_get	按 ID 或键获取完整记忆
memory_related	沿着一条记忆的关联链接进行遍历
remember	保存一条事实；如果与现有记忆近似重复，则会拒绝保存并返回冲突的记忆，而 key 会替换当前持有该键的记忆
memory_update	修改字段、设置或清除键、置顶、归档、确认（confirm）内容仍然成立，或提出异议（dispute）
memory_link / memory_unlink	将两条记忆关联起来，或解除关联
memory_review	日常整理：检查可能重复、孤立、过长、过时、未读和有争议的记忆，以及距离上限的余量

导出和导入没有对应工具：它们面向用户和脚本，而且无论是否调用，工具定义都会在每个会话中消耗令牌。

这些工具返回的是记忆服务自身的 text——压缩到预算内的纯文本呈现——而不是其外围的 JSON。这是下方规则的一个更具体的适用场景，并非例外：这种呈现仍由引擎生成，同时返回两者会消耗记忆服务旨在节省的双倍令牌。不含 text 的正文会像其他答案一样以 JSON 返回。

它只是一个翻译器，仅此而已

它没有自己的凭据，没有数据库，也不会做出任何 API 不会做的决定。每个工具都会调用一次 api.gagarin.cloud，并携带调用者自己的 bearer token；每次拒绝都是引擎的拒绝，未经修改地传递出来。

这是其他一切赖以成立的特性：拥有此服务不会带来任何权限。正因如此，在单一写入关口前放置一个公共端点才是安全的；绝不能以任何方式修改这里的内容来削弱这一点。

有两点值得说明，因为它们看起来都像是遗漏：

• 回答是引擎的 JSON，而不是摘要。 每个服务、账本行和连接都已带有引擎编写的 sentence，正是为了确保终端和仪表板不会对同一行作出不同描述。这里再增加一种渲染方式，就意味着又多了一种需要保持一致的说法。
• 错误格式为 [code] message，并附带一行 hint:，这是 gg 的输出格式。统一格式后，读过 Gagarin 技能说明的 Agent 无需再学习第二种格式，就能识别这里返回的内容。如果引擎发送的内容超出信封——例如 memory_duplicate 会附带近似重复项——这些内容会追加在提示信息之后，而不会被丢弃。

它刻意无法完成的工作

有四件事需要机器来做；如果在这里提供这些功能，就会产生看起来像是平台故障的错误：

• 构建并推送镜像。 gg ship 将构建、推送和部署合并为一个步骤，会在源代码所在的位置调用 docker。这里的 deploy 会运行一个已经位于 Gagarin 注册表中的镜像：CI 推送的标签，或重新部署的版本。将镜像推送到那里是 CLI 的职责。
• 打开隧道。 gg connect 会绑定一个本地端口。
• 等待作业完成。 run 会提交并返回一个修订版本，与这里的其他写入操作一样。gg run 会一直阻塞，直到运行结束，并以脚本自身的退出码退出，这是流水线所需要的行为；通过 MCP，你需要轮询 status 来查看阶段和代码。
• 点击审批。 按照设计，这需要由有收件箱的人来完成。

此仓库中也没有资源类型、大小或范围的列表。这些由引擎负责定义，它会在拒绝请求时指出具体内容；如果在这里使用 z.enum，就会在另一个仓库中维护第二份列表，一旦新增类型就会出错——这个代码库过去已经在 gg 中针对这类值犯过一次同样的错误。

运行位置

它运行在 Kubernetes 集群中，靠近控制平面，而不是与网站和控制台一起运行在 Vercel 上。 网站和控制台位于 Scaleway 之外，因为它们的职责是即使平台宕机，也依然在线并报告这一情况。API 无法访问时，这个服务完全无话可说；它就是换了一种形态的 API，因此它应该靠近 API，通过集群内 Service 访问，而不是绕经负载均衡器发出请求再返回。

这个 Pod 以没有 RBAC 权限且未挂载令牌的 ServiceAccount 运行，并使用只读根文件系统。它不需要这些权限或令牌。

每次推送到 main 都会构建镜像并滚动部署—— .github/workflows/deploy.yml。能够执行这些操作的凭据属于 production 环境的机密，且只有 main 可以使用，因此拉取请求不会在这些凭据旁运行。合并到 main 就是在部署。

添加工具

在 src/tools.ts 中调用一次 server.registerTool：提供一个名称、一段说明调用者最需要知道的规则的描述、一个 zod 结构，以及一次 api.call。然后在 src/tools.test.ts 中添加测试，断言路径、方法和请求体——只有这些地方可能悄无声息地出错；如果部署向错误路径发送 PUT 请求，就会返回 404，看起来就像服务不存在。

不要为 API 不支持的功能添加工具。此文件绝不应该成为功能首次出现的地方。