跳转至

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,或者用逗号分隔的 工具名。写了不存在的工具名,服务启动时就报错退出,并列出所有合法的工具名。

$ DOSI_MCP_TOOLS=compile_sql,explain_query dosi-server --mcp-stdio --model dosi/model.yaml

带 --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 要指向真正建好模型所需表的库:

$ duckdb orders.duckdb < $DOSI_EXAMPLES/orders/seed.sql
$ dosi-server --model $DOSI_EXAMPLES/orders/model.yaml --db orders.duckdb

错误

引擎的失败以工具级错误返回(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

下一步