MCP 服务¶
dosi-server 原生支持
Model Context Protocol,
所以 AI Agent(Claude Code、Codex、OpenCode,或任何 MCP 客户端)可以发现指标和维度、
把指标查询编译成方言 SQL 并执行,中间不需要一层 HTTP 垫片。
这些 MCP 工具调用的是与 REST API 相同的引擎接缝,
返回的 JSON 形态和结构化错误也与 dosi --format json 一致。
一方的最佳搭档是 datus-agent —— Datus 自己的 data agents,用来端到端地完成数据工程与数据分析:建模、管道,以及在其之上的分析。 Dosi 为它们提供指标层,因此 Agent 算出来的数字,与整套技术栈其余部分用的是同一份定义。
协议:面向 MCP 规范 2026-07-28,端到端无状态:
没有 initialize 握手,没有 Mcp-Session-Id 头,客户端元数据随每个请求的
_meta 一起携带。旧版(2026-07-28 之前)客户端同样以无会话方式服务,
简单的请求/响应式工具调用会得到普通的 application/json 回复。
负载均衡后的任何副本都能服务任何请求,会话状态一律不驻留在服务端。
想找上手指南?
本页是参考手册。要把 Dosi 接进 Agent,先看 在 Agent 里使用 Dosi:装上 Dosi 插件,它会替你启动这个服务;或者 自己启动 MCP 服务,接到任意 MCP 客户端。
传输方式¶
Streamable HTTP(主要方式)¶
每个运行中的 dosi-server 都会把 MCP 挂在 POST /mcp 上(顶层路径,
不在 /v1 之下),与 REST API 并列:
export DOSI_EXAMPLES=~/.local/share/dosi/examples
dosi-server --model $DOSI_EXAMPLES/orders/model.yaml --db orders.duckdb
curl -s -X POST localhost:8081/mcp \
-H 'content-type: application/json' \
-H 'accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
这个路径就是安装脚本放内置示例模型的地方; 换成任何一份 Apache Ossie(原 OSI)模型文件都一样能跑。
/mcp 上还有两条请求层面的规则:必须带 Host 头(rmcp 的 DNS 重绑定防护,
缺失时返回 400 且没有响应体);请求体上限 1 MiB,实际只会限制
validate_model,更大的模型改用 dosi validate 校验。
设置了 --auth-token(环境变量 DOSI_SERVER_TOKEN)时,/mcp 会像 API 其余部分
一样要求 Authorization: Bearer <token>,每个请求都校验,
这正是无状态部署需要的。Claude Code 的远程配置:
claude mcp add --transport http dosi http://localhost:8081/mcp \
--header "Authorization: Bearer $DOSI_SERVER_TOKEN"
stdio(本地单客户端)¶
--mcp-stdio 通过 stdin/stdout 提供 MCP,不绑定 HTTP,
这是本地 Agent 把服务作为子进程拉起的标准做法。日志走 stderr,
stdout 上只有协议内容。
claude mcp add dosi -- \
dosi-server --model /path/to/model.yaml \
--db /path/to/warehouse.duckdb --mcp-stdio
客户端要指向安装好的二进制(若 dosi-server 不在客户端的 PATH 上就写绝对
路径),绝不要指向 cargo run——MCP 客户端分不清编译和卡死。
常规的那些参数都适用(--connections、--db、--disable-execute、
--osi-basic 等);两种传输方式提供完全相同的工具集。
会话中模型可以改¶
建模或改模型的 Agent 整个对话只和一个服务进程打交道,所以 --mcp-stdio 下服务会跟着文件走,
而不是只在启动时加载一次(--lazy-model,加 --mcp-stdio 时默认打开;传 --lazy-model false
可关闭,HTTP 模式下传 --lazy-model 可打开):
- 每次调用模型相关的工具前,按修改时间和大小比对模型文件(目录形式的模型比对其中每个文件,
本体和映射文件也算),有变化就重新编译。正在执行的调用用它开始时的模型完成。
get_capabilities(按需列出)报告模型的generation,每重载一次加 1。 - 模型不存在或有错时服务不退出。模型相关的工具返回
no_model(附上它在找的路径)或model_invalid(附上和validate_model相同的issues/compile_errors),文件改好后 下一次调用就成功。文件改过之后,绝不会继续用上一个可用的模型作答。validate_model、list_connections、get_capabilities始终可用。 - 连接文件也同样跟踪;条目没变的连接保留原来的连接池。
--env-file <path>(dotenv 格式,每行KEY=VALUE;环境变量DOSI_ENV_FILE)为连接文件中 环境里没有设置的${VAR}提供值,文件变化时重新读取。会话开始后才写进去的口令,下一次调用就会用上; 值不会出现在任何输出里。
claude mcp add dosi -- \
dosi-server --mcp-stdio --model dosi/model.yaml \
--connections dosi-connections.yaml --env-file ~/.config/dosi/secrets.env
不加这个开关时(HTTP 默认)行为不变:启动时编译一次模型,模型不存在或有错时以状态码 2 退出。
服务端只暴露工具,没有 MCP resources,也没有 prompts;此外还带一段
instructions,说明"发现 → 预览 → 执行"的工作流,并要求客户端读结构化错误、
不要原样重试。
所有工具都带 readOnlyHint: true,这样会拦写操作的宿主(Codex 的 exec
模式遇到无法询问的工具调用会直接拒绝)也能调用它们。dosi 只生成 SELECT
语句,但过滤条件(where_sql、context_filter)和参数值由数仓求值,dosi
不检查其中调用的函数有没有副作用(比如 PostgreSQL 的 nextval、
dblink_exec)。run_query、select、attribute_metrics、attribute_dimensions 会执行查询;
如果宿主是靠这个标记让它们无人值守地运行,请给连接配一个只读的数据库账号。
工具¶
| 工具 | 输入 | 返回 |
|---|---|---|
list_datasets |
— | 数据集:名称、来源、主键、字段、时间维度 |
list_metrics |
— | 每个指标一行简表:name、kind、expr(怎么算出来)、datasets、description;适用时还有 window(一行写出的窗口)、required_dimensions 和 requires_time_axis(查询必须怎么分组)、params(参数名)和 time_dimension。其余内容见 describe_metric |
list_dimensions |
metric(可选) |
dataset.field 名称,带时间标记和粒度,每行附 is_dimension(是否值得分组)与 source(declared,或命中的推断规则)。给了 metric 就只返回该指标能分组的字段,推荐的在前 |
describe_metric |
name |
单个指标的完整描述:expr(怎么算出来,过滤指标写成 <base> FILTER (WHERE …))、dimension_datasets(能按哪些数据集分组和筛选)、params(含它读的 fixed 字段的参数,带 declared_on)、time_granularities(只列它读的每个窗口都接受的粒度)、required_dimensions(查询必须分组的维度:窗口和细节层次的排除维度、fixed 的键)和 requires_time_axis,排名类指标还有 compares_across;参数化指标还带 param_schema(params 的 JSON Schema);未知名称会返回候选项 |
describe_dataset |
name |
单个数据集的完整描述:描述、键、时间轴、每个字段(计算字段带 expr,fixed 字段带 fixed(base, 键…) 声明、它读的数据集和 time_axis),以及从它这边看的关系;未知名称会返回候选项 |
list_connections |
— | 具名的数仓配置:名称、类型、方言、default、status(ready;missing_env 并列出变量名;或 error 及其 code) |
get_capabilities |
— | 引擎模式、支持的方言、是否启用执行、live、model_status,以及模型统计和 generation |
compile_sql |
指标查询 + dialect、pretty |
{dialect, sql},不执行 |
explain_query |
指标查询 | 以文本形式给出的逻辑计划 |
run_query |
指标查询 + dialect、connection、row_limit、include_sql |
{dialect, outputs, columns, rows, row_count, row_limit_applied};include_sql: true 时再带 sql |
attribute_metrics |
metric、baseline/current 两期 + where_sql、context_filter、params、group_by、dialect、connection |
指标变化按公式拆分:status、指标树 tree(每个节点的两期值和贡献 effect)、issues(见指标归因) |
attribute_dimensions |
同上 + dimensions、top_groups |
指标变化按 dimensions 的分组拆分,多个维度是一条逐层下钻路径:分组树 tree,带 effect、others 和 groups_total;不给维度时返回错误,candidates 列出可拆的字段 |
compile_select |
明细查询 + dialect、pretty |
{dialect, sql},不执行(查询明细行) |
explain_select |
明细查询 | 明细计划的文本形式——看清楚选了哪些连接 |
select |
明细查询 + dialect、connection、row_limit、include_sql |
{dialect, columns, rows, row_count, row_limit_applied},行级记录;include_sql: true 时再带 sql |
validate_model |
model_yaml |
{valid, issues, compile_errors, warnings} |
指标查询类的输入就是 REST API 和 CLI 所用的那个 MetricQuery 传输形态
(metrics、写作 [{field, grain}] 的 group_by、where_sql、
context_filter、time_range、order_by、limit、params)。工具的 schema 由同一批类型生成,
不可能产生漂移。要看某个市场在全部市场里的名次,把它写在 where_sql;
要只在这个市场内部排名,用 context_filter(见过滤条件)。
每次响应里的 warnings 列出查询中某个部分读不到的条件。
明细查询类的输入同样就是 DetailQuery 的传输形态(from、fields、
where_sql、time_range、order_by、limit)。答案是记录而不是聚合值时
用 select——"列出最大的 100 笔订单"、"这个月哪些合同到期"。它有两种拒绝
值得读一读再改,而不是盲目重试:detail_fanout 说明根会被一对多的一跳放大,
并给出应该改用的根;ambiguous_join_path 列出点名各条候选路径的关系前缀。
两者都给出可以直接粘进下一次调用的 suggested_retry
(见查询明细行)。
列出哪些工具¶
每个工具的名称、描述和输入 schema 在 Agent 第一次调用之前就进了它的上下文,
所以服务默认只列出回答数据问题要用的工具。有五个工具按需列出:compile_sql、
compile_select、explain_query、explain_select(run_query 和 select
传 include_sql: true 就会自己带上 SQL),以及 get_capabilities。用
--mcp-tools 或环境变量 DOSI_MCP_TOOLS 打开它们:写 all,或者用逗号分隔的
工具名。写了不存在的工具名,服务启动时就报错退出,并列出所有合法的工具名。
带 --disable-execute 启动的服务,不管 --mcp-tools 怎么写,都列出
compile_sql 和 compile_select,换掉 run_query、select、attribute_metrics
和 attribute_dimensions:后面这几个在这种服务上只能被拒绝。服务没列出的工具,
tools/call 也不认。REST API 不受影响。
执行方面的保护¶
run_query 复用服务端的执行机制:并发信号量
(--max-concurrent-executions,占满时返回 busy)、执行超时
(--execute-timeout-secs,超时返回 timeout),以及 --disable-execute
(这时 run_query 根本不会列出,见列出哪些工具)。注意
--request-timeout-secs 不覆盖 /mcp,约束 run_query 的只有上面两项。
select 走同一套机制,同样受这三个开关约束。
结果会进入 LLM 上下文,所以行数有上限:没写 limit 的指标查询自动加
LIMIT 500,row_limit 最高钳制在 5000;明细查询默认 LIMIT 100,
最高钳制在 10000——调用方自己写的更大的 limit 同样会被钳制。
实际生效的上限由 row_limit_applied 报出,Agent 据此能分辨截断页和完整结果。
不带 connection 时,查询跑在连接文件里标了 default: true 的连接上,和
dosi query --execute 一样;没有标默认连接时跑在服务端的本地 DuckDB 上(--db 指定的文件或内存库)。
只编译的工具也默认用默认连接的方言。执行类工具默认不返回编译出的 SQL,要看就传 include_sql: true
(Agent 会话里每次调用的 SQL 长达数万字符,没人读);compile_sql 和 compile_select 照常返回 SQL。
run_query 需要有数据
不带 --db 时,本地 DuckDB 是内存库且没有灌数据,于是 compile_sql
正常、run_query 报表不存在。--db 要指向真正建好模型所需表的库:
错误¶
引擎的失败以工具级错误返回(isError: true),携带引擎的结构化 JSON,
字段与 REST API 和 CLI 相同:稳定的 code、candidates、suggested_retry。
名字写错时,错误里会给出合法拼写:
{"error": {"code": "unknown_metric", "message": "unknown metric \"revenu\"",
"metrics": ["revenu"],
"candidates": ["revenue", "order_count", "unique_customers",
"avg_order_value", "total_margin"]}}
如果要改的不是名字而是查询形状,suggested_retry 会用散文说清楚——它是一个
字符串,不是查询对象:
{"error": {"code": "grain_on_non_time_dimension",
"message": "orders.status is not a time dimension; a grain cannot be applied",
"suggested_retry": "drop the :grain suffix or mark the field with dimension.is_time: true"}}
工具参数本身不合法时,拦截发生在更早一层——由工具 schema 直接拒绝:
{"grain": "fortnight"} 返回的是纯文本反序列化错误,列出合法取值
(day、week、month、quarter、year),而不是 {"error": …} 结构。
Agent 应当读错误再改查询,而不是原样重试。服务端的 MCP 指引里也是这么写的。
交互式试用¶
npx @modelcontextprotocol/inspector \
dosi-server --model $DOSI_EXAMPLES/orders/model.yaml \
--db orders.duckdb --mcp-stdio
下一步¶
-
传输方式、工具白名单,以及让 Agent 老老实实走指标的提示词规则。
-
用 stdio 或 HTTP 启动,接到任意 MCP 客户端,并设定 Agent 能做什么。