通过 MCP 扩展 IaC Code

更新时间:
复制 MD 格式

IaC Code 可以作为模型上下文协议(Model Context Protocol,MCP)Client 连接外部工具、服务和数据源。本文通过 Filesystem MCP Server 说明如何添加、验证和调用 MCP,并介绍远程Server、配置范围及安全要求。

前提条件

  • 已完成安装和配置 IaC Code。

  • 已进入需要使用 MCP Server 的项目目录。

  • 运行本文的 Stdio 示例时,已安装 Node.js 和 npx。

  • 已审查 MCP Server 来源、启动命令、依赖版本和所需权限。

支持的连接方式

IaC Code 支持 Stdio、HTTP、SSE 和 URL-only WebSocket 类型的 MCP Server,并发现其工具、资源和提示词。MCP Server 既可以由本地子进程启动,也可以作为远程服务访问。

添加并验证本地 MCP Server

以下示例使用官方 Filesystem MCP Server,仅允许访问当前项目目录。在项目根目录运行:

iac-code mcp add filesystem \
  --scope local \
  -- npx -y @modelcontextprotocol/server-filesystem "$PWD"

预期结果:IaC Code 将 filesystem 写入当前项目的本地 MCP 配置。然后查看配置并执行有界健康检查:

iac-code mcp list
iac-code mcp get filesystem --scope local --check

预期结果:列表显示 Server 名称、local 范围和 stdio 传输类型;健康检查结果中的connection_state 为 connected,并显示已发现的工具数量。Filesystem MCP Server 不提供资源或提示词接口,因此相应能力探测可能显示 Method not found,不影响已发现工具的使用。健康检查只短暂连接,完成后会自动退出。

在 REPL 中调用 MCP 工具

  1. 在同一个项目目录运行 iac-code。

  2. 输入 /mcp,选择 filesystem 并查看其连接状态和工具列表。

  3. 输入以下请求:

    使用 filesystem MCP Server 列出当前项目根目录的条目,只读取,不要修改任何文件。
  4. 检查工具名、参数和访问目录后批准只读调用。

预期结果:IaC Code 调用 filesystem 提供的目录读取工具,并返回当前项目中的条目。完成验证后,如不再需要该配置,可运行:

iac-code mcp remove filesystem --scope local

在 Web 版中管理和调用 MCP

打开使用同一项目的 Web 会话,然后进入“设置 > 插件 > MCP”。Web 版支持:

  • 添加或编辑 Stdio、HTTP、SSE 和 WebSocket Server。

  • 查看作用域、连接状态、认证状态、错误信息以及已发现的工具、资源和提示词。

  • 启用、停用或删除配置,批准或拒绝项目级 Server,并执行连接检查。

  • 为支持 OAuth 的远程 Server 发起登录、重新认证或清除认证。

确认 filesystem 显示为已连接后,返回会话并提交与 REPL 相同的目录读取请求。Web 会在工具卡片中展示 MCP Server、工具参数和结果;检查后批准只读调用。也可以直接在 MCP面板中添加前述 Filesystem 配置,不必先运行命令行管理命令。

连接远程 MCP Server

已取得服务方提供的 URL 后,可以使用 HTTP 传输添加远程 Server:

iac-code mcp add --transport http <server-name> <https-mcp-server-url>

如果服务使用 OAuth,继续运行:

iac-code mcp auth <server-name>
iac-code mcp get <server-name> --check

IaC Code 会打开或输出授权地址,并通过本机回环地址接收回调。服务要求预分配 Client ID、Client Secret 或特定 OAuth 元数据时,请按 GitHub MCP 配置文档操作,不要把 Client Secret明文写入配置文件。

MCP 配置范围

范围

默认文件

说明

user

~/.iac-code/settings.yml

当前用户的所有项目可用。

local

<项目>/.iac-code/settings.local.yml

仅当前检出使用,适合本机私有配置。

project

<项目>/.mcp.json

可由项目共享,但每个 Server 都需要本地信任审批。

session

ACP 创建会话时传入

只在对应 ACP 会话运行时生效。

项目中的 .mcp.json 可能启动本地进程,因此不会被自动信任。交互式 REPL 会要求逐个审批;Headless、ACP 和 A2A 不会弹出审批,尚未获批的项目 Server 会被跳过并输出警告。

权限和安全

  • 只连接可信 MCP Server;使用前审查启动命令、依赖版本、工具描述和请求权限。

  • 为 Stdio Server 固定依赖版本;为远程 Server 使用 HTTPS、可信证书和认证,并限制域名。

  • MCP Header 和环境变量中的 Secret 使用 ${VAR} 引用或 OAuth 安全存储,不写入.mcp.json 或版本库。

  • MCP 工具仍受 IaC Code 权限框架约束。对写文件、执行命令、外部网络和云上写操作保持最小授权,并核对每次调用的参数。

  • 修改项目 MCP 配置会使已有审批失效,不能为消除审批提示而关闭安全检查。

常见问题

MCP Server 启动失败

先运行 iac-code mcp get <name> --config-only 检查已脱敏配置,再运行iac-code mcp get <name> --check 查看有界诊断。Stdio Server 还需确认命令存在、依赖已安装、工作目录正确;Windows 上的 Node.js Server 通常需要通过 cmd /c npx 启动。

MCP 工具不可见

在 REPL 的 /mcp 或 Web 的“设置 > 插件 > MCP”中检查 Server 是否被禁用、等待项目审批、需要 OAuth 或连接失败。修改配置后重新连接;命令行可运行iac-code mcp reconnect <name>。

OAuth 完成后仍提示未认证

确认浏览器回调到达运行 IaC Code 的本机,并再次执行健康检查。需要重新授权时,先运行iac-code mcp reset-auth <name> 清除该 Server 的已存认证状态,再运行 mcp auth。

相关文档