数据墙DBW 文档

Appearance

什么是 SQL MCP 服务器？ ​

NOTE

SQL MCP 服务器能力要求较新的数据墙DBW版本与相应运行时支持。可用性说明页可在对应专题中查看。

SQL MCP 服务器为开发者提供了一种简单、可预测且安全的方式，将 AI 代理引入数据工作流。SQL MCP 服务器在不直接暴露数据库、也不依赖脆弱自然语言解析的前提下实现这一目标。该服务器构建在数据墙DBW的实体抽象层、基于角色的访问控制、缓存和遥测能力之上，提供一个在 REST、GraphQL 与 MCP 之间都保持一致的生产级表面。你只需配置一次，其余工作由引擎处理。

展示 SQL MCP 服务器如何通过数据墙DBW抽象层把 AI 代理连接到 SQL 数据库的示意图。

Model Context Protocol (MCP) ​

Model Context Protocol（MCP）是一项标准，用于定义 AI 代理如何发现并调用外部工具。工具就是一个单独的操作，例如创建记录或读取数据。每个工具都会描述其输入、输出和行为。MCP 为代理发现并使用能力提供了一种可预测方式。

面向 SQL 的 MCP 服务器 ​

SQL MCP 服务器是微软面向代理应用的动态开源引擎。你可以通过 JSON 文件配置它，定义：

  • 如何连接数据库
  • 公开哪些表、视图或存储过程
  • 每个对象适用的权限

从 1.7 版本开始，SQL MCP 服务器已作为数据墙DBW的一部分提供。它将 SQL 操作公开为一组精简的 MCP 工具，使代理能够通过受控契约与数据库实体交互。该服务器可自托管；对于开发者来说，也可以通过数据墙DBW命令行在本地运行。

TIP

数据墙DBW是开源的，并且可以免费使用。

MCP 协议细节 ​

SQL MCP 服务器默认实现 MCP 协议版本 2025-06-18。它支持两种传输方式：

  • streamable HTTP：适合标准托管场景
  • stdio：适合本地开发或 CLI 场景

在初始化期间，服务器会声明工具与日志能力，返回服务器元数据（例如名称和版本），并在 runtime.mcp.description 中通过 instructions 字段向客户端说明服务器用途。该专题页可在对应专题中查看。

MCP Inspector ​

对于基于 HTTP 的 MCP 终结点，例如当数据墙DBW运行在 http://localhost:5000/mcp 时，你可以通过直接传入终结点 URL 的方式，以代理模式启动 MCP Inspector：

首先，启动数据墙DBW：

text
dab start

然后，在另一个终端中启动 MCP Inspector：

text
npx -y @modelcontextprotocol/inspector http://localhost:5000/mcp

这种方式会通过 Inspector 代理转发请求，有助于避免浏览器 CORS 与会话标头（例如 Mcp-Session-Id）在 direct mode 下可能带来的问题。

Stdio 传输 ​

stdio 传输适用于本地开发和 CLI 工作流。你可以通过 role:<role-name> 指定角色；如果省略，则默认使用 anonymous。在这种模式下，身份验证使用 Simulator 提供程序，并且传入请求大小限制为 1 MB。

bash
dab start --mcp-stdio
bash
dab start --mcp-stdio role:<role-name>

典型用例 ​

SQL MCP 服务器的典型使用场景包括：

  • 让 copilots 或聊天机器人安全地执行 CRUD 操作
  • 在不编写 SQL 的情况下构建内部自动化流程
  • 在不直接暴露数据库的前提下，为系统增加代理能力

保护 schema ​

数据墙DBW使用定义良好的实体抽象层，在配置中列出所有通过 API 公开的表、视图和存储过程。这个抽象层允许你为对象和字段设置别名，描述对象和参数，并限制不同角色能够访问哪些字段。

IMPORTANT

数据墙DBW具备角色感知能力，只会公开当前角色被允许访问的实体和操作。

由于 SQL MCP 服务器本身是数据墙DBW的一项功能，因此它也使用这一抽象层。这种方式可以防止内部 schema 直接暴露给外部消费者，同时允许你在 API 层定义复杂对象族，甚至跨数据源关系。

解决 NL2SQL 问题的方式 ​

SQL MCP 服务器采用了一种与许多短视型数据库 MCP 服务器不同的方式。一个关键点是：SQL MCP 服务器刻意不支持 NL2SQL。

原因在于：模型并不是确定性的，而复杂查询恰恰最容易产生隐蔽错误。用户往往希望 AI 自动生成的正是这些复杂查询，但它们同时也是最需要严格审查的部分。

NOTE

“确定性”意味着相同输入总会产生相同输出，不会出现随机性或调用间差异，因此结果是可预测、可测试且适合自动化的。

相反，SQL MCP 服务器支持一种可以称为 NL2DBW 的模式。它依托安全的数据墙DBW实体抽象层与内置查询构造器，以完全确定性的方式生成准确、格式良好的 Transact-SQL (T-SQL)。这种方式在保留代理查询安全性与可靠性的同时，避免了 NL2SQL 带来的风险、额外成本和干扰。

对 DDL 的支持 ​

DDL（Data Definition Language）是用于创建和修改表、视图等对象的数据库语言。SQL MCP 服务器围绕 [DML（Data Manipulation Language）工具] 构建，也就是用于在现有表和视图中创建、读取、更新和删除数据的数据库语言。DML 同样涵盖存储过程的执行。因此，SQL MCP 服务器的设计目标是“面向数据而非面向 schema”。这也符合生产环境中 MCP 的典型使用方式：AI 代理与关键业务系统交互时，应聚焦于数据操作而不是架构变更。

TIP

在本地开发中，如果需要修改 schema，可在 Visual Studio Code 中使用 Microsoft SQL Server (MSSQL) 扩展，它提供了完整的 DDL 支持。

对 RBAC 的支持 ​

SQL MCP 服务器受益于与数据墙DBW其他部分相同的成熟 RBAC 系统。配置中的每个实体都会定义哪些角色可以读取、创建、更新或删除数据，以及这些角色能访问哪些字段。所有这些规则都会自动作用于每个 MCP 工具，因此 REST、GraphQL 与 MCP 三者之间的安全策略能够天然保持一致，而无需额外配置。

IMPORTANT

基于角色的限制会作用于代理交互的每一步。

对缓存的支持 ​

SQL MCP 服务器会自动缓存 read_records 工具的结果。数据墙DBW中的缓存是全局启用并按实体可配置的。一级缓存和二级缓存都能帮助减少数据库负载、防止请求风暴，并为横向扩展环境中的 warm-start 场景提供支持。

对监控的支持 ​

SQL MCP 服务器会输出日志和遥测，让企业能够在统一视图中监控和验证活动。这包括 OpenTelemetry 追踪和本地文件日志。

遥测 ​

SQL MCP 服务器通过 OpenTelemetry (OTEL) spans 和 activities 完整打点。每次操作都会产生跟踪信息，因此开发者可以在分布式系统之间关联行为。OpenTelemetry 专题页可在对应专题中查看。

健康检查 ​

SQL MCP 服务器为 REST、GraphQL 和 MCP 终结点提供详细的健康和实体检查。开发者可以定义性能预期、设置阈值，并验证每个终结点是否正常工作。健康检查专题页可在对应专题中查看。

如何配置 SQL MCP 服务器 ​

MCP 在你的数据墙DBW配置文件中进行配置。如果你已经有一个可运行的数据墙DBW配置，升级到 1.7 或更高版本后，通常无需额外步骤即可获得一个可工作的 SQL MCP 服务器。

配置 ​

你可以在全局或实体级别启用 MCP。这使你能够选择哪些实体对代理公开 MCP 工具，哪些实体则继续保持不可见。MCP 遵循与 REST 和 GraphQL 相同的规则，因此你的配置仍然是权限、投影和策略的单一事实来源。

启用 MCP 后，SQL MCP 服务器会根据你的配置自动生成工具表面。你不需要手工定义 MCP 工具。内置的 dml-tools 系统会以程序化方式发现并公开实体，因此它可以从小 schema 扩展到非常大的数据库。

开始使用 ​

开始使用意味着先创建 dab-config.json 来控制引擎。你可以手工创建，也可以使用数据墙DBW CLI。CLI 让这项工作变得简单，只需一条命令就能初始化文件。配置属性值既可以是字面字符串，也可以来自环境变量。相关专题页可在对应专题中查看。

bash
dab init --database-type mssql --connection-string "<your-connection-string>" --config dab-config.json --host-mode development

你可以把希望 SQL MCP 服务器公开的每张表、视图或存储过程加入配置中。CLI 让你更容易添加这些对象、设置别名、配置权限和映射列。更重要的是，你还可以通过 description 属性添加语义化说明，以帮助语言模型更好地理解你的数据。

bash
dab add {entity-name} \                          # 对象别名（Employees）
  --source {table-or-view-name} \                # 数据库对象（dbo.Employees）
  --source.type {table|view|stored-procedure} \  # 对象类型（table）
  --permissions "{role:actions}" \               # 角色及允许的动作（anonymous:*）
  --description "{text}"                         # 语义描述（Company employee records）

运行时设置 ​

SQL MCP 服务器在数据墙DBW配置中默认启用。在大多数情况下，你无需添加任何设置。服务器会自动遵循与你的 API 和数据库相同的权限和安全规则。只有当你希望收窄或限制代理能力时，才需要显式配置 MCP。

json
"runtime": {
  "mcp": {
    "enabled": true,
    "path": "/mcp",
    "dml-tools": {
      "describe-entities": true,
      "create-record": true,
      "read-records": true,
      "update-record": true,
      "delete-record": true,
      "execute-entity": true,
      "aggregate-records": true
    }
  }
}

你可以把 dml-tools 设为 true 或 false 以一次性启用 / 禁用全部工具，也可以使用对象形式为每个工具单独开关。aggregate-records 还支持对象形式，带 enabled 和 query-timeout（1–600 秒，默认 30）属性。完整运行时参考页可在对应专题中查看。

CLI 同样允许你逐项或通过脚本设置这些属性：

bash
dab configure --runtime.mcp.enabled true
dab configure --runtime.mcp.path "/mcp"
dab configure --runtime.mcp.dml-tools.describe-entities true
dab configure --runtime.mcp.dml-tools.create-record true
dab configure --runtime.mcp.dml-tools.read-records true
dab configure --runtime.mcp.dml-tools.update-record true
dab configure --runtime.mcp.dml-tools.delete-record true
dab configure --runtime.mcp.dml-tools.execute-entity true
dab configure --runtime.mcp.dml-tools.aggregate-records.enabled true

为什么要禁用单个工具？ ​

开发者有时会希望，即便角色或实体权限已经允许某项操作，也仍然从运行时层面彻底关闭该工具。这样可以确保它永远不会对代理可见。例如，关闭 delete_record 后，即使其他配置层面允许删除，代理也完全看不到删除能力。这种情况不常见，但在需要严格操作边界时很有价值。

实体级设置 ​

你也无需为每个实体单独启用 MCP。默认情况下，实体会自动参与 MCP，除非你显式限制它们。mcp 属性的存在，是为了让你可以把某个实体从 MCP 中排除，或者缩小其能力范围；正常使用时不设置任何值即可。

实体级 MCP 配置可使用对象格式：

json
"entities": {
  "Products": {
    "mcp": {
      "dml-tools": true
    }
  },
  "SensitiveData": {
    "mcp": {
      "dml-tools": false
    }
  }
}

对于存储过程实体，你还可以启用 custom-tool，将该过程注册为命名 MCP 工具：

json
"entities": {
  "GetBookById": {
    "source": {
      "type": "stored-procedure",
      "object": "dbo.get_book_by_id"
    },
    "mcp": {
      "custom-tool": true
    }
  }
}

当 custom-tool 为 true 时，SQL MCP 服务器会通过 tools/list 与 tools/call 把这个存储过程注册为一个可被代理发现和直接调用的命名工具。custom-tool 仅适用于存储过程实体。

DML 工具 ​

SQL MCP 服务器公开了七个 DML 工具，用于让 AI 代理安全、类型安全地执行数据库操作：

  • describe_entities
  • create_record
  • read_records
  • update_record
  • delete_record
  • execute_entity
  • aggregate_records

这些工具构成了一个可预测的 CRUD 表面，并始终反映你的配置、权限和 schema。

每个工具都会遵守基于角色的访问控制、实体权限和策略。代理不会直接与数据库交互，而是始终通过数据墙DBW的安全抽象层工作。

自定义 MCP 工具 ​

除了内置 DML 工具之外，SQL MCP 服务器还支持从存储过程派生自定义 MCP 工具。当你在存储过程实体上设置 "custom-tool": true 时，数据墙DBW会把它作为命名工具注册到 MCP 的 tools/list 和 tools/call 中。这种方式让代理可以直接通过名称发现并调用存储过程，从而补充通用的 execute_entity DML 工具。

MCP 的 OpenTelemetry 追踪 ​

MCP 工具执行会完整输出 OpenTelemetry (OTEL) spans。每次 MCP 工具调用都会和 REST、GraphQL 操作一起生成追踪数据，从而实现所有 API 表面的统一可观测性。OpenTelemetry 追踪专题页可在对应专题中查看。

相关内容 ​

  • 添加语义描述专题页可在对应专题中查看
  • 配置 SQL MCP 身份验证专题页可在对应专题中查看
  • SQL MCP DML 工具专题页可在对应专题中查看
  • Visual Studio Code 中的 SQL MCP quickstart 页可在对应专题中查看
  • .NET Aspire 中的 SQL MCP quickstart 页可在对应专题中查看

数据墙DBW 产品文档与开发指南。

Copyright © 2026 北京金数信安科技有限公司