MCP / Agent Access

Dory 提供 MCP 访问能力，让外部 AI Agent 可以安全读取 Dory 中的连接、Schema、保存查询、监控摘要，并执行受限制的只读 SQL。

适用场景

在 Codex 或 Claude 中查询 Dory 的数据库连接。
让 Agent 搜索表、视图和字段。
读取表结构、DDL、统计信息和数据预览。
执行只读 SQL 并限制返回行数。
基于结果构建分析上下文或图表建议。
读取 ClickHouse 监控摘要。

创建访问令牌

打开 Dory 设置。
进入 Agent Access。
输入令牌名称，例如 Codex 或 Claude Desktop。
点击创建令牌。
复制新生成的 token。该 token 只会完整显示一次。

令牌前缀为 dory_mcp_。如果丢失完整 token，需要撤销后重新创建。

默认权限范围

新令牌默认包含以下只读和分析权限：

Scope	能力
`connections:read`	读取连接列表、数据库和表信息。
`query:read`	预览表数据，执行只读 SQL。
`analysis:run`	构建结果上下文、图表 profile 和分析动作。
`schema:read`	搜索 Schema、读取表 profile。
`saved_queries:read`	读取保存的查询。
`monitoring:read`	读取监控摘要和慢查询 / 错误查询样本。

MCP 工具不会返回数据库密码或连接密钥。

Codex CLI 示例

在本机环境中设置 token：

export DORY_MCP_TOKEN="dory_mcp_xxx"
codex mcp add dory --url https://your-dory.example.com/api/mcp --bearer-token-env-var DORY_MCP_TOKEN
codex mcp list

如果使用桌面端并启用了本地 MCP Proxy，请使用 Dory 设置页展示的本地 endpoint。

通用 MCP JSON 示例

{
  "mcpServers": {
    "dory": {
      "type": "http",
      "url": "https://your-dory.example.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${DORY_MCP_TOKEN}"
      }
    }
  }
}

可用工具概览

Dory MCP 当前提供的主要工具包括：

Tool	用途
`dory_list_connections`	列出当前 token 可见的 Dory 连接。
`dory_list_databases`	列出某个连接下的数据库。
`dory_list_tables`	列出数据库中的表和视图。
`dory_describe_table`	读取列、类型和表元数据。
`dory_get_database_summary`	生成数据库级摘要。
`dory_get_table_profile`	读取表 profile 和统计信息。
`dory_search_schema`	按表、视图或字段名搜索 Schema。
`dory_list_saved_queries`	列出 token 可读取的 Saved Queries。
`dory_get_saved_query`	读取单个 Saved Query。
`dory_get_monitoring_summary`	读取支持数据库的监控摘要。
`dory_preview_table`	预览表中的少量行。
`dory_run_readonly_sql`	执行带行数限制的只读 SQL。
`dory_build_result_context`	将查询结果转换成 Agent 友好的上下文。
`dory_build_chart_profile`	根据结果形状生成图表建议。
`dory_run_analysis`	执行更高层的分析动作。

其中 dory_run_readonly_sql 会拒绝写入类 SQL，并限制最大返回行数。

Agent 工作流

使用 dory_list_connections 选择正确连接。
使用 dory_list_databases 和 dory_list_tables 找到相关对象。
写 SQL 前，先用 dory_describe_table 或 dory_search_schema 查看字段和类型。
使用 dory_preview_table 获取小样本。
使用 dory_run_readonly_sql 执行已审查的 SELECT 查询。
使用 dory_build_result_context 或 dory_build_chart_profile 总结结果。

安全建议

为每个客户端创建独立 token，便于审计和撤销。
不要把 token 写进仓库。
团队环境中通过 TRUSTED_ORIGINS 限制可信来源。
如果某个客户端不再使用，及时撤销对应 token。
生产库仍建议使用只读数据库账号，MCP 的只读限制不能替代数据库权限设计。

常见问题排查

现象	可能原因	处理方式
MCP 客户端返回 401	Token 缺失或无效。	重新创建 token，并更新客户端环境变量。
客户端看不到连接	Token 缺少 `connections:read`，或当前用户没有连接权限。	使用正确的 Dory 账号和组织重新创建 token。
SQL 被拒绝执行	语句不是只读查询，或包含不支持的语法。	使用明确的 `SELECT` 查询，移除写入操作。
返回行数过少	MCP 结果行数限制生效。	先在 SQL 中聚合或过滤，再请求更多结果。
客户端无法连接	URL 错误，或客户端无法访问 Dory。	检查 `/api/mcp` URL 是否可从客户端环境访问。

这篇文档有帮助吗？

本页内容