连接本地 MCP 客户端

NOTE

本文档是实践教程，侧重于完整的工作流程演示。如需了解单个功能的配置方法（如身份验证、语义描述等），请参阅操作指南中的 MCP 集成 章节。

AI 编程助手（VS Code + GitHub Copilot、Claude Desktop 等）通过 MCP 协议可以直接与数据库交互。本教程演示如何在本地搭建数据墙DBW MCP 服务，并配置常用客户端连接。

前提条件

• 已安装 dab CLI（1.7+）。
• 已安装至少一个支持 MCP 的客户端（VS Code 或 Claude Desktop）。
• 有一个可访问的关系型数据库（SQL Server、PostgreSQL、MySQL 等）。

第一步：准备数据库和配置

NOTE

Stdio 模式下，数据墙DBW 会自动使用 Simulator 身份验证提供程序，覆盖配置文件中的身份验证设置。这意味着你无需配置 JWT 或外部身份提供者，直接通过 role:<role-name> 指定角色即可。

创建示例数据库：

CREATE DATABASE ProductsDb;
GO
USE ProductsDb;
GO

CREATE TABLE dbo.Products (
    Id INT PRIMARY KEY,
    Name NVARCHAR(100) NOT NULL,
    Inventory INT NOT NULL,
    Price DECIMAL(10,2) NOT NULL,
    Cost DECIMAL(10,2) NOT NULL
);

INSERT INTO dbo.Products VALUES
    (1, 'Action Figure', 40, 14.99, 5.00),
    (2, 'Building Blocks', 25, 29.99, 10.00),
    (3, 'Puzzle 500 pcs', 30, 12.49, 4.00),
    (4, 'Toy Car', 50, 7.99, 2.50),
    (5, 'Board Game', 20, 34.99, 12.50);

创建配置文件：

dab init \
  --database-type "mssql" \
  --connection-string "Server=localhost;Database=ProductsDb;User Id=sa;Password=YourPassword;TrustServerCertificate=true;Encrypt=true;" \
  --host-mode "Development"

添加产品实体，授予读写权限，并添加描述帮助 AI 理解：

dab add Product \
  --source "dbo.Products" \
  --permissions "anonymous:read,authenticated:*" \
  --description "产品目录，包含名称、库存、售价和成本信息"

dab update Product \
  --fields.name "Id" \
  --fields.description "产品唯一标识符" \
  --fields.primary-key "true"

dab update Product \
  --fields.name "Name" \
  --fields.description "产品名称"

dab update Product \
  --fields.name "Inventory" \
  --fields.description "当前库存数量"

dab update Product \
  --fields.name "Price" \
  --fields.description "零售单价，单位为人民币元"

dab update Product \
  --fields.name "Cost" \
  --fields.description "单位成本，单位为人民币元"

第二步：确认 MCP 已启用

{
  "runtime": {
    "mcp": {
      "enabled": true
    }
  }
}

默认启用。如果没有，通过 CLI 开启：

dab configure --runtime.mcp.enabled true

第三步：配置 VS Code

在项目根目录创建 .vscode/mcp.json：

{
  "servers": {
    "sql-mcp-server": {
      "type": "stdio",
      "command": "dab",
      "args": [
        "start",
        "--mcp-stdio",
        "role:anonymous",
        "--config", "${workspaceFolder}/dab-config.json",
        "--LogLevel", "error"
      ]
    }
  }
}

配置说明：

• type: "stdio"：通过标准输入/输出通信，不打开网络端口。
• role:anonymous：以匿名角色运行。如需写入权限，改为 role:authenticated。
• --LogLevel error：减少 stdout 输出，避免干扰 MCP 协议通信。

VS Code 会自动识别该文件，GitHub Copilot 即可通过 MCP 工具查询数据库。

测试对话

在 VS Code 中与 Copilot 对话，尝试以下问题：

• "查询产品表中所有数据"
• "有哪些产品库存低于 30？"
• "计算所有产品的平均售价"
• "产品'Building Blocks'的售价和成本是多少？"

Copilot 会自动调用 describe_entities 了解数据库结构，然后通过 read_records 查询数据。

第四步：配置 Claude Desktop

编辑 claude_desktop_config.json（位置见 Claude 设置）：

{
  "mcpServers": {
    "sql-mcp-server": {
      "type": "stdio",
      "command": "dab",
      "args": [
        "start",
        "--mcp-stdio",
        "role:anonymous",
        "--config", "C:\\\\Users\\\\username\\\\projects\\\\dab-config.json",
        "--LogLevel", "error"
      ]
    }
  }
}

IMPORTANT

Claude Desktop 配置中的 --config 路径必须使用绝对路径，不能使用 ~ 或相对路径。Windows 使用 C:\\path\\to\\dab-config.json，macOS/Linux 使用 /Users/username/projects/dab-config.json。

重启 Claude Desktop 后，在设置中确认 MCP 服务器状态为已连接。

客户端使用场景

对话示例	代理调用
"查询库存少于 30 的产品"	describe_entities → read_records with filter
"创建一个新产品"	create_record
"更新 Toy Car 的价格为 9.99"	read_records（查 Id）→ update_record
"计算所有产品的总库存量"	aggregate_records with sum

实践建议

建议	说明
先用只读角色	开发阶段用 anonymous + read 权限，确认查询无误后再开放写入
补充字段描述	代理依赖描述来理解数据，Name 不如 "产品名称" 清晰
日志设为 Error	Stdio 模式下日志输出到 stdout 会干扰 MCP 消息，设为 Error 最省心
配置文件用绝对路径	部分客户端 (Claude Desktop) 不支持相对路径和变量
不用的工具关闭	如果不需要代理修改数据，全局关闭 create/update/delete 相关的 dml-tools

下一步

• 在 AI 应用中接入 MCP — 在自定义 AI 应用中集成 MCP。
• 在容器环境中运行 MCP — MCP 服务的容器化部署。
• MCP 故障排查 — 解决连接和工具调用问题。