altimate-code MCP服务器与ACP支持:连接AI数据工具生态的完整指南
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 后端。
一、先搞清楚: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不会被插值
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 成本分析
也就是说,你在编辑器里对话,背后干活的还是那套完整的数据工程工具箱:
五、生态全景:MCP + ACP + 插件怎么搭配?
三者不是替代关系,而是分工明确:
- 内置 100+ 数据工程工具(tools.md):开箱即用,覆盖 dbt、SQL、仓库探查
- MCP 服务器:接入社区/公司内部的通用工具(文件系统、数据库、内部 API……)
- TypeScript 插件/自定义工具(custom-tools.md):写专属逻辑,还能挂接 30+ 生命周期钩子
- ACP:把以上所有能力输出给任何兼容编辑器
六、常见问题速查
| 问题 | 答案 |
|---|---|
| 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 分析。
更多细节可查阅:
- MCP 配置详解:docs/docs/configure/mcp-servers.md
- ACP 支持说明:docs/docs/configure/acp.md
- MCP 客户端核心实现:packages/opencode/src/mcp/index.ts
- ACP 服务实现:packages/opencode/src/acp/service.ts



