← 完整教程目录离线阅读器与全文搜索

03|本地 MCP 接入:先看工具和请求,再生成

本教程使用公开 atlascloud-mcp 包的本地 stdio 路线。它与 CLI 源码里的实验性 atlas-mcp 二进制、插件里的远程 OAuth 服务不是同一条安装路径。只需要本地 MCP 时,不必再为它编译 Go 源码。

准备一个能启动本地 MCP 进程的宿主、该包所需 Node.js 环境,以及自己的 Atlas API key。包 README 当前写 Node.js >=18;正式发布教程时仍要核对当前包 engines 和团队支持的 Node.js 版本,不要据此建议使用已停止维护的旧版本。

状态:正文已完成;未执行线上付费生成或宿主实连。依据:S1 / S2 / S3。本地测试范围见 验证报告。

先决定密钥放在哪里

不要把真实 API key 写进教程、公共配置、截图或 Agent 对话。使用宿主提供的密钥配置,或让从终端启动的宿主继承环境变量。下面是在 Bash 中输入环境变量的一种方式,不会把密钥正文写进这条 Shell 命令:

read -r -s -p 'Atlas API key: ' ATLASCLOUD_API_KEY
printf '\n'
export ATLASCLOUD_API_KEY

这不是系统密钥链,环境变量仍可能被有权限的进程访问。GUI 中启动的宿主也未必继承你刚刚设置的终端环境;连接失败时应核对进程实际获取密钥的方式,不要不停创建新 key。

配置服务进程

对于使用 mcpServers 配置结构、并能让子进程继承所需环境变量的宿主,服务声明的形态如下:

{
  "mcpServers": {
    "atlascloud": {
      "command": "npx",
      "args": ["-y", "atlascloud-mcp"]
    }
  }
}

将这段合并进宿主的配置,不要覆盖原有其他 MCP。它没有包含密钥:你必须通过宿主支持的安全方式提供 ATLASCLOUD_API_KEY。如果宿主使用不同结构,按它的实际格式填写同一进程命令,不能直接复制整段。

团队部署应在联调通过后固定已验证的 npm 包版本,避免每次连接都依赖浮动版本;记录版本,但不要凭空填一个版本号。

第一条消息只做发现

检查已连接的 atlascloud MCP。先列出实际可用的工具,再查询文本生成图片的模型,并读取一个候选模型的参数 schema。不要调用聊天模型,不上传文件,不生成媒体,不更换我的账户或凭据。

期望看到可调用的模型发现与详情工具,例如 atlas_list_models 和 atlas_get_model_info。必须以当前连接返回的工具 schema 为准,不能因为 README 出现过一个名字,就假定当前服务一定提供它。

第二条消息只预览

按刚才选定的文本生图模型,准备一张无文字的抽象网站配图。使用生成工具的 dry_run 预览完整请求,不提交。解释模型、必填参数和默认值;如果没有可靠价格信息,明确说估价仍未知。

在实际工具 schema 确认存在这些字段后,图像生成请求形态可以是:

{
  "model": "替换为已查询的真实模型ID",
  "params": {
    "prompt": "An abstract visual for a developer tool website, no text."
  },
  "dry_run": true
}

这只是调用结构示意,params 必须补上该模型当前必填项。dry_run 的作用是展示将提交的请求,不代表返回了可锁定的价格。公开实现存在 schema 无法取得时跳过验证的路径,因此还需确认该模型的完整 schema 确实取得,不能把 dry_run 当成无条件严格校验。已有参考文件的任务也不要在“只预览”的要求下偷偷调用上传工具。

用户授权后生成一张

再次确认模型、数量、费用认知与输入未变,随后提交一次。保存实际返回的 prediction ID,后续通过 atlas_get_prediction 查询它。不要假设 MCP 返回的字段与 CLI 一样,也不要因为一次工具调用等待结束就再提交。

媒体结果通常包含远程链接。宿主能够下载时,保存并检查实际文件;不能下载时交付真实链接并说明未保存本地文件。这个 MCP 的上传工具在文档中用于临时素材,不是长期资产托管。

怎样算连接成功

成功启动服务只是第一步。应依次证明:工具可发现,模型 schema 可读取,dry_run 没有提交任务,经授权的生成能查回结果。不要以“配置文件没有报错”代替这四项检查。

本地 stdio 服务不能直接靠粘贴一个 URL 接入网页宿主。需要远程 MCP 时应使用对应的公开接入文档,本篇不猜测服务地址或 OAuth 配置。

运行路径、授权与状态约定见 通用执行说明。