Skip to content

mcp.md

Latest commit

 

History

History
70 lines (47 loc) · 2.62 KB

mcp.md

File metadata and controls

70 lines (47 loc) · 2.62 KB

MCP Integration

Model Context Protocol (MCP) allows AI clients to control CosmosDBShell programmatically.

Start MCP Server

dotnet run --project CosmosDBShell -- --mcp
dotnet run --project CosmosDBShell -- --mcp 5050

Bare --mcp starts the HTTP server on the default port 6128.

VS Code Setup

Requires VS Code 1.103+

Enable Autostart (Recommended)

  1. Open Settings (Ctrl+,)
  2. Search for chat.mcp.autostart
  3. Select newAndOutdated

MCP servers will start automatically without manual refresh.

Manual Start

  1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
  2. Run MCP: List Servers
  3. Select localCosmosDBShellServer → Start Server
  4. Check Output tab for startup confirmation

Security

How MCP Works

The MCP server runs locally with your user permissions. Connected clients can execute shell commands, which means they can:

  • Read database/container metadata
  • Query and retrieve documents
  • Create, update, and delete resources

Database and container resource actions are executed through Azure Resource Manager when an ARM context is attached (Entra ID connections). MCP sessions connected with account keys, emulator credentials, or static data-plane tokens fall back to the Cosmos DB data plane for these actions.

For deterministic ARM routing in multi-subscription environments, start the shell with --connect-subscription and --connect-resource-group.

Data Exposure

Your MCP client may use a remote LLM. Command outputs, query results, and file contents could be transmitted to external services. Treat all shell output as potentially shared.

Best Practices

Risk Mitigation
DNS rebinding Origin header validated on all requests; non-loopback origins rejected
Unauthorized access Bind to localhost only, don't expose port publicly
Credential leakage Use Azure AD instead of connection strings/keys
Excessive permissions Apply least-privilege RBAC, narrow scopes
Missing management-plane scope For ARM-routed actions, connect with Entra ID and grant Cosmos DB Operator or equivalent scoped permissions; otherwise the shell falls back to the data plane
Accidental destruction Review tool requests, don't auto-approve deletes
Unnecessary exposure Disable --mcp when not needed

Checklist

  • Only enable on trusted machines/networks
  • Keep port bound to 127.0.0.1
  • Use Azure AD/managed identity authentication
  • Review and approve destructive operations manually
  • Don't share secrets (keys, PII) in prompts or outputs
  • Disable MCP mode when not actively using it