# 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](../SOURCES.md)。本地测试范围见 [验证报告](../verification/REPORT.md)。

## 先决定密钥放在哪里

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

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

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

## 配置服务进程

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

```json
{
  "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 确认存在这些字段后，图像生成请求形态可以是：

```json
{
  "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 配置。


运行路径、授权与状态约定见 [通用执行说明](../common/EXECUTION.md)。
