Azure Cosmos DB Shell 模型上下文协议设置

在 Azure Cosmos DB Shell 中启用模型上下文协议 （MCP） 服务器，以允许 AI 助手和应用程序以编程方式与 Cosmos DB 资源交互。

什么是 MCP？

模型上下文协议（MCP）是一种开放标准，使 AI 助手能够与外部工具和系统交互。 在 Cosmos DB Shell 中启用时，它允许：

• AI 助手：使用 AI 助手查询和管理 Cosmos DB 数据
• 自动化工作流：创建与数据库交互的工作流
• 集成：将 Cosmos DB 与其他 AI 支持的应用程序集成
• 数据探索：使 AI 能够浏览和分析数据

先决条件

• 已安装 Azure Cosmos DB Shell （Installation Guide）
• 带Azure Cosmos DB扩展的 VS Code （建议）
• 对 MCP 概念的基本理解
• 与 localhost 的网络连接（MCP 服务器在本地运行）

启用 MCP 服务器

步骤 1：访问 VS Code 设置

1. 打开 VS Code
2. 转到“设置”（Ctrl+、/Cmd+、）
3. 搜索“Cosmos DB”

步骤 2：配置 MCP 设置

将以下设置添加到 VS Code settings.json：

{
  "cosmosDB.shell.MCP.enabled": true,
  "cosmosDB.shell.MCP.port": 6128,
  "cosmosDB.shell.MCP.startOnLaunch": true,
  "cosmosDB.shell.MCP.bindToLocalhost": true
}

设置详细信息：

步骤 3：重启 VS Code

关闭并重新打开 VS Code 以应用设置。

验证 MCP 服务器是否正在运行

检查 MCP 状态

1. 打开 Cosmos DB Shell 输出面板
2. 查找确认消息：

   MCP Server started on http://localhost:6128
   

测试 MCP 连接

打开终端并测试 MCP 服务器：

# On Windows
curl http://localhost:6128/health

# On macOS/Linux
curl http://localhost:6128/health

预期响应：

{
  "status": "healthy",
  "version": "1.0.213-preview"
}

MCP 配置选项

最小配置（建议）

对于大多数用户，最少的配置就足够了：

{
  "cosmosDB.shell.MCP.enabled": true
}

这使用默认设置：

• 端口：6128
• 自动启动：已启用
• Localhost 绑定：已启用

高级配置

对于自定义配置：

{
  "cosmosDB.shell.MCP.enabled": true,
  "cosmosDB.shell.MCP.port": 6129,
  "cosmosDB.shell.MCP.startOnLaunch": false,
  "cosmosDB.shell.MCP.bindToLocalhost": true,
  "cosmosDB.shell.MCP.timeout": 30000,
  "cosmosDB.shell.MCP.maxConnections": 10,
  "cosmosDB.shell.MCP.logLevel": "info"
}

高级设置：

手动 MCP 服务器启动

如果禁用了自动启动，请手动启动 MCP 服务器：

在 VS Code 中

1. 打开命令面板 （Ctrl+Shift+P / Cmd+Shift+P）
2. 键入“Cosmos DB：启动 MCP 服务器”
3. 按 Enter

从命令行

cosmosdbshell --mcp

这会在默认端口 6128上启动 MCP。

若要使用其他端口，请将其作为位置参数传递：

cosmosdbshell --mcp 6128

还可以在 VS Code 设置中配置 cosmosDB.shell.MCP.port 。

将 MCP 与 AI 助手配合使用

示例 1：Claude/ChatGPT 借助工具

配置 AI 客户端以连接到 MCP 服务器：

{
  "mcpServers": {
    "cosmosdb": {
      "command": "cosmosdbshell",
      "args": ["--mcp"],
      "env": {
        "MCP_PORT": "6128"
      }
    }
  }
}

示例 2：通过 MCP 查询

配置后，AI 助手可以：

"Query all users from the 'users' container in the 'mydb' database"

MCP 服务器将此转换为：

cd /mydb/users
query "SELECT * FROM c"

示例 3：数据分析

"Count documents by status in the users container and show me the breakdown"

MCP 服务器执行：

query "SELECT c.status, COUNT(*) as count FROM c GROUP BY c.status"

使用 MCP 进行身份验证

MCP 服务器使用与 Cosmos DB Shell 相同的身份验证：

• Entra ID （建议）

  • 使用Azure标识进行身份验证
  • 最安全的方法
  • 需要适当的 RBAC 角色

• 托管标识（生产环境）

  • 自动使用 VM 或应用服务托管标识
  • 最适合Azure托管的应用程序
  • 要求身份拥有 Cosmos DB 权限

• 帐户密钥 （开发）

  • 使用连接字符串中的账户密钥
  • 快速进行测试
  • 安全性较低，应避免用于生产环境

安全注意事项

MCP 服务器安全最佳做法

• 仅本地绑定 （默认值）

  "cosmosDB.shell.MCP.bindToLocalhost": true
  

  • 将 MCP 服务器限制为 localhost
  • 阻止远程访问
  • 建议：保持启用此功能

• 网络隔离

  • 在隔离网络中运行 MCP 服务器
  • 使用防火墙规则阻止外部访问
  • 不要向公共 Internet 公开端口 6128

• 身份验证

  • 使用Entra ID进行身份验证
  • 实现 RBAC 最小权限访问
  • 定期轮换帐户密钥

• 审核和监视

  • 启用 MCP 服务器日志记录
  • 监视 MCP 服务器活动
  • 定期查看可疑活动的日志

连接安全性

安全配置：

{
  "cosmosDB.shell.MCP.enabled": true,
  "cosmosDB.shell.MCP.bindToLocalhost": true,
  "cosmosDB.shell.MCP.logLevel": "info"
}

故障排除

MCP 服务器不会启动

问题： MCP 服务器无法启动

解决方案：

1. 检查端口可用性：

   # Windows
   netstat -ano | findstr 6128
   
   # macOS/Linux
   lsof -i :6128
   

2. 请尝试不同的端口：

   "cosmosDB.shell.MCP.port": 6129
   

3. 检查防火墙设置

4. 查看 VS Code 输出面板以获取错误消息

连接被拒绝

问题： AI 客户端无法连接到 MCP 服务器

解决方案：

1. 验证 MCP 是否已启用并启动
2. 检查正确的端口号（默认值：6128）
3. 确保已启用 localhost 绑定
4. 检查防火墙是否允许 localhost 连接

身份验证失败

问题： MCP 服务器无法向 Cosmos DB 进行身份验证

解决方案：

1. 验证 Cosmos DB Shell 身份验证是否正常工作：

   cosmosdbshell
   

2. 检查Entra ID权限

3. 验证托管标识是否已分配正确的角色

4. 在开发环境中使用账户密钥进行测试

性能问题

问题： MCP 服务器速度缓慢或无响应

解决方案：

1. 如果请求过多，请减少 maxConnections ：

   "cosmosDB.shell.MCP.maxConnections": 5
   

2. 增加慢查询的超时时间：

   "cosmosDB.shell.MCP.timeout": 60000
   

3. 检查网络连接

4. 监视系统资源（CPU、内存、磁盘）

已在使用的端口

问题： 端口 6128 已在使用中

解决方案：

1. 使用端口查找和停止进程：

   # Windows
   netstat -ano | findstr 6128
   taskkill /PID <PID> /F
   
   # macOS/Linux
   lsof -i :6128
   kill -9 <PID>
   

2. 更改 MCP 端口：

   "cosmosDB.shell.MCP.port": 6129
   

查看 MCP 日志

启用调试日志记录

{
  "cosmosDB.shell.MCP.logLevel": "debug"
}

访问日志

日志显示在 VS Code 输出面板中：

1. 打开输出面板（查看 > 输出）
2. 从下拉列表中选择“Cosmos DB Shell”
3. 查看 MCP 服务器日志

停止 MCP 服务器

在 VS Code 中

1. 打开命令面板 （Ctrl+Shift+P / Cmd+Shift+P）
2. 键入“Cosmos DB：停止 MCP 服务器”
3. 按 Enter

从命令行

# Kill the MCP server process
# The shell will exit when you type:
exit

高级场景

具有多个 Cosmos DB 帐户的 MCP

为每个帐户创建单独的 MCP 实例：

{
  "cosmosDB.shell.MCP.enabled": true,
  "cosmosDB.shell.MCP.port": 6128,
  "cosmosDB.shell.MCP.accounts": [
    {
      "name": "production",
      "endpoint": "https://prod.documents.azure.cn:443/",
      "port": 6128
    },
    {
      "name": "staging",
      "endpoint": "https://staging.documents.azure.cn:443/",
      "port": 6129
    }
  ]
}

使用自定义 AI 代理的 MCP

将 MCP 与自定义 AI 代理集成：

import requests

# Query Cosmos DB via MCP server
response = requests.post(
    'http://localhost:6128/query',
    json={
        'database': 'mydb',
        'container': 'users',
        'query': 'SELECT * FROM c WHERE c.status = "active"'
    }
)

results = response.json()
print(results)

后续步骤

• 快速入门指南 - 基本命令入门
• 命令参考 - 了解所有可用的命令
• 安全最佳做法 - 查看安全准则
• 故障排除指南 - 解决常见问题

另请参阅

• Azure Cosmos DB Shell 概述
• Visual Studio Code 扩展指南
• 模型上下文协议文档