altimate-code MCP服务器与ACP支持:连接AI数据工具生态的完整指南

原创2026-10-27 12:29:391,709 阅读

altimate-code MCP服务器与ACP支持:连接AI数据工具生态的完整指南

altimate-code 是一款开源的 AI 数据工程智能体(agentic data engineering)工具,内置 100+ 数据工程工具,支持 dbt、SQL 与 10 种云数据仓库。它原生支持 MCP(Model Context Protocol)服务器 接入与 ACP(Agent Client Protocol) 协议,让你把外部工具生态和自己的编辑器都接进这个 AI 数据助手。本篇是面向新手的完整指南,从零讲清如何配置、如何管理、如何把 altimate-code 变成编辑器的 AI 后端。

altimate-code 终端界面截图

一、先搞清楚:MCP 和 ACP 分别解决什么问题?

很多人看到这两个缩写会晕,其实它们方向正好相反:

协议 一句话理解 altimate-code 的角色
MCP 把"外部工具"接进来 它是 客户端,连接你配置的 MCP 服务器,使用其中的工具
ACP 把"自己"接出去 它是 服务端,让 Zed、Neovim 等编辑器把它当作 AI 后端

一句话总结:MCP 让 altimate-code 的手变多(更多工具),ACP 让 altimate-code 的家变多(更多编辑器)。

两者的官方配置文档分别位于 mcp-servers.md 和 acp.md。

二、连接 MCP 服务器:两种类型,三种认证

altimate-code 通过项目配置文件(.altimate-code/altimate-code.json)声明 MCP 服务器,分为 local(本地子进程) 和 remote(远程 HTTP) 两种类型。

1. 本地 MCP 服务器:跑在你机器上的工具进程

{
  "mcp": {
    "my-tools": {
      "type": "local",
      "command": ["npx", "-y", "@my-org/mcp-server"],
      "environment": { "API_KEY": "${MY_API_KEY}" }
    }
  }
}
  • command 是启动服务器的命令数组,altimate-code 会像普通子进程一样拉起它,通过 stdio 通信
  • ${VAR} 语法会从环境变量安全注入(JSON 转义,适合密钥);{env:VAR} 则用于原样注入结构化值
  • 变量未设置且无默认值时解析为空字符串,裸 $VAR 不会被插值

altimate-code 数据工程演示:从想法到生产 dbt 模型

2. 远程 MCP 服务器:连接远程 HTTP 端点

{
  "mcp": {
    "remote-tools": {
      "type": "remote",
      "url": "https://mcp.example.com/sse",
      "headers": { "Authorization": "Bearer {env:MCP_TOKEN}" }
    }
  }
}

远程服务器支持 SSE 与 Streamable HTTP 两种传输方式,认证上有三档玩法:

  • 静态 headers:固定令牌直接写进 headers
  • OAuth 认证:配置 oauth 块(client_id、authorization_url、token_url),首次连接自动拉起浏览器授权,令牌本地安全存储,过期可一键重新认证
  • 动态令牌 headersCommand:这是数据工程场景的杀手锏。比如 Microsoft Fabric Core MCP 这类使用短时效 Entra ID 令牌的服务器,可以配置一条命令在每次连接时重新计算 Authorization 头——令牌过期自动刷新,无需改配置

3. 常用字段速查

字段 类型 说明
type local / remote 服务器类型
enabled boolean 启用/禁用(默认 true)
timeout number 超时毫秒数(默认 5000)
headersCommand object 由命令动态生成 header 值(走 execFile,不经过 shell)
oauth object / false OAuth 配置;显式设为 false 可关闭自动探测

⚠️ 小坑提醒:一旦你提供了 Authorization 头(无论静态还是动态),OAuth 自动探测会自动禁用,避免两条认证路径打架。

三、CLI 一键管理 MCP 服务器

不用手改 JSON,altimate-code mcp 子命令把日常操作都包办了(实现见 cli/cmd/mcp.ts):

# 查看所有服务器及连接状态(带认证状态图标 ✓/⚠/✗)
altimate-code mcp list

# 添加本地服务器
altimate-code mcp add --name my-tools --type local --command "node ./server.js" --env API_KEY=secret

# 添加远程服务器并附带请求头
altimate-code mcp add --name remote-tools --type remote --url https://example.com/mcp --header "Authorization=Bearer TOKEN"

# OAuth 认证 / 清除凭据
altimate-code mcp auth my-tools
altimate-code mcp logout my-tools

# 排查 OAuth 连接问题
altimate-code mcp debug my-tools

# 移除配置
altimate-code mcp remove my-tools

💡 mcp add 默认写入项目配置(.altimate-code/altimate-code.json),加 --global 则写入全局配置 ~/.config/altimate-code/,方便团队协作时区分个人与项目级工具。

四、ACP 支持:把 altimate-code 接进你的编辑器

ACP 让 altimate-code 成为符合 Agent Client Protocol 标准的智能体后端。只需一条命令启动:

altimate acp

它会通过 stdin/stdout 的 NDJSON 流与编辑器通信,底层复用完整的会话、工具与权限体系(协议层实现见 acp/agent.ts,CLI 入口见 cli/cmd/acp.ts)。

各编辑器接入方式

Zed(settings.json):

{
  "language_models": {
    "altimate": { "command": ["altimate", "acp"] }
  }
}

Neovim(ACP 插件):

require("acp").setup({ command = { "altimate", "acp" } })

JetBrains 系 IDE:在设置中将 altimate 配置为外部 AI Provider 即可。

ACP 模式提供什么?

  • ✅ 通过你已配置的任意 LLM Provider 访问模型
  • ✅ 完整工具执行:文件读写、搜索、Shell 命令
  • ✅ Agent 选择与切换(Builder / Analyst / Plan 等模式)
  • ✅ 全部 100+ 数据工程工具——SQL 校验、列级血缘、dbt 操作、FinOps 成本分析

也就是说,你在编辑器里对话,背后干活的还是那套完整的数据工程工具箱:

altimate-code 数据仓库分析演示:重构 dbt 模型

五、生态全景:MCP + ACP + 插件怎么搭配?

三者不是替代关系,而是分工明确:

  1. 内置 100+ 数据工程工具(tools.md):开箱即用,覆盖 dbt、SQL、仓库探查
  2. MCP 服务器:接入社区/公司内部的通用工具(文件系统、数据库、内部 API……)
  3. TypeScript 插件/自定义工具(custom-tools.md):写专属逻辑,还能挂接 30+ 生命周期钩子
  4. ACP:把以上所有能力输出给任何兼容编辑器

altimate-code 列级血缘 diff 演示:PR 审查中的数据工程工具

六、常见问题速查

问题 答案
MCP 连接失败怎么排查? 先 altimate-code mcp list 看状态,再用 altimate-code mcp debug <name> 定位 OAuth 链路
令牌过期了要重配吗? 不用。headersCommand 每次连接重新解析;OAuth 令牌用 mcp auth 一键刷新
项目和个人工具如何隔离? mcp add 默认写项目配置,--global 写全局配置
调高 MCP 超时怎么配? 在配置中加 "experimental": { "mcp_timeout": 10000 }
ACP 模式下能用 MCP 工具吗? 能,ACP 复用同一套会话与工具注册体系

写在最后

MCP 让 altimate-code 从"自带 100+ 工具"变成"无限可扩展",ACP 则让它从"终端里的智能体"变成"任何编辑器的 AI 大脑"。对数据工程师来说,这两块能力意味着:内部工具链一键接入、在熟悉的编辑器里直接让 AI 跑 dbt 和 SQL 分析。

更多细节可查阅:

登录后查看全文
altimate-code