--- layout: Conceptual title: Azure Cosmos DB Shell Model Context Protocol Setup - Azure Cosmos DB | Microsoft Learn canonicalUrl: https://learn.microsoft.com/en-us/azure/cosmos-db/shell/model-context-protocol-setup uhfHeaderId: MSDocsHeader-NoSQL permissioned-type: public recommendations: true recommendation_types: - Training - Certification breadcrumb_path: ../../breadcrumb/azure-nosql/toc.json feedback_system: Standard feedback_product_url: https://feedback.azure.com/d365community/forum/3002b3be-0d25-ec11-b6e6-000d3a4f0858 feedback_help_link_url: /answers/tags/187/azure-cosmos-db/ feedback_help_link_type: get-help-at-qna ms.service: azure-cosmos-db ms.subservice: nosql ms.reviewer: mjbrown ms.author: sasinnat author: sajeetharan description: Set up and configure the Model Context Protocol (MCP) server for Azure Cosmos DB Shell to enable AI-powered database interactions. ms.collection: - ce-skilling-ai-copilot ms.topic: how-to ms.update-cycle: 180-days ms.date: 2026-10-19T00:00:00.0000000Z ai-usage: ai-assisted locale: en-us document_id: 3a4d0073-2a7a-963f-7cf1-608b6c23fb76 document_version_independent_id: 3a4d0073-2a7a-963f-7cf1-608b6c23fb76 updated_at: 2026-10-29T12:08:00.0000000Z original_content_git_url: https://github.com/MicrosoftDocs/nosql-docs-pr/blob/live/azure/cosmos-db/shell/model-context-protocol-setup.md gitcommit: https://github.com/MicrosoftDocs/nosql-docs-pr/blob/d544fbd677e5c098756dbf81dcc8b6ff167255c1/azure/cosmos-db/shell/model-context-protocol-setup.md git_commit_id: d544fbd677e5c098756dbf81dcc8b6ff167255c1 site_name: Docs depot_name: Learn.azure-nosql page_type: conceptual toc_rel: ../toc.json word_count: 1189 asset_id: cosmos-db/shell/model-context-protocol-setup moniker_range_name: monikers: [] item_type: Content source_path: azure/cosmos-db/shell/model-context-protocol-setup.md cmProducts: - https://authoring-docs-microsoft.poolparty.biz/devrel/cd668c2f-f5b3-4573-8ad1-019570e3e2db - https://authoring-docs-microsoft.poolparty.biz/devrel/911a44a7-2f6c-477c-810f-dc8b7d425cce spProducts: - https://authoring-docs-microsoft.poolparty.biz/devrel/cc82e69d-afbe-4554-9f4c-6705fc860c42 - https://authoring-docs-microsoft.poolparty.biz/devrel/14f2b9d5-6f06-45a8-ac5f-313eaa351153 platformId: 43102c66-2267-d144-c575-f13baa9b3b8b --- # Azure Cosmos DB Shell Model Context Protocol Setup - Azure Cosmos DB | Microsoft Learn Enable the Model Context Protocol (MCP) server in Azure Cosmos DB Shell to allow AI assistants and applications to interact with your Cosmos DB resources programmatically. ## What is MCP? The Model Context Protocol (MCP) is an open standard that enables AI assistants to interact with external tools and systems. When enabled in Cosmos DB Shell, it allows: - **AI Assistants**: Use AI assistants to query and manage your Cosmos DB data - **Automated Workflows**: Create workflows that interact with your databases - **Integration**: Integrate Cosmos DB with other AI-powered applications - **Data Exploration**: Enable AI to explore and analyze your data ## Prerequisites - Azure Cosmos DB Shell installed ([Installation Guide](install)) - VS Code with Azure Cosmos DB extension (recommended) - Basic understanding of MCP concepts - Network connectivity to localhost (MCP server runs locally) ## Enable MCP server ### Step 1: Access VS Code settings 1. Open VS Code 2. Go to Settings (Ctrl+, / Cmd+,) 3. Search for "Cosmos DB" ### Step 2: Configure MCP settings Add the following settings to your VS Code `settings.json`: ```json { "cosmosDB.shell.MCP.enabled": true, "cosmosDB.shell.MCP.port": 6128, "cosmosDB.shell.MCP.startOnLaunch": true, "cosmosDB.shell.MCP.bindToLocalhost": true } ``` **Setting Details:** | Setting | Value | Description | | --- | --- | --- | | `cosmosDB.shell.MCP.enabled` | `true` | Enable MCP server | | `cosmosDB.shell.MCP.port` | `6128` | Port number (default: 6128) | | `cosmosDB.shell.MCP.startOnLaunch` | `true` | Auto-start MCP on shell launch | | `cosmosDB.shell.MCP.bindToLocalhost` | `true` | Bind only to localhost (secure) | ### Step 3: Restart VS Code Close and reopen VS Code to apply settings. ## Verify MCP server is running ### Check MCP status 1. Open the Cosmos DB Shell output panel 2. Look for confirmation message: ``` MCP Server started on http://localhost:6128 ``` ### Test MCP connection Open a terminal and test the MCP server: ```bash # On Windows curl http://localhost:6128/health # On macOS/Linux curl http://localhost:6128/health ``` Expected response: ```json { "status": "healthy", "version": "1.0.213-preview" } ``` ## MCP configuration options ### Minimal configuration (recommended) For most users, minimal configuration is sufficient: ```json { "cosmosDB.shell.MCP.enabled": true } ``` This uses default settings: - Port: 6128 - Auto-start: Enabled - Localhost binding: Enabled ### Advanced configuration For custom configurations: ```json { "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" } ``` **Advanced Settings:** | Setting | Value | Description | | --- | --- | --- | | `cosmosDB.shell.MCP.timeout` | Milliseconds | Request timeout (default: 30000) | | `cosmosDB.shell.MCP.maxConnections` | Number | Maximum concurrent connections (default: 10) | | `cosmosDB.shell.MCP.logLevel` | `debug`/`info`/`warn`/`error` | Logging level (default: `info`) | ## Manual MCP server start If you disabled auto-start, manually start the MCP server: ### In VS Code 1. Open command palette (Ctrl+Shift+P / Cmd+Shift+P) 2. Type "Cosmos DB: Start MCP Server" 3. Press Enter ### From command line ```bash cosmosdbshell --mcp ``` This starts MCP on the default port `6128`. To use a different port, pass it as a positional argument: ```bash cosmosdbshell --mcp 6128 ``` You can also configure `cosmosDB.shell.MCP.port` in VS Code settings. ## Using MCP with AI assistants ### Example 1: Claude/ChatGPT via tools Configure your AI client to connect to the MCP server: ```json { "mcpServers": { "cosmosdb": { "command": "cosmosdbshell", "args": ["--mcp"], "env": { "MCP_PORT": "6128" } } } } ``` ### Example 2: Query via MCP Once configured, your AI assistant can: ``` "Query all users from the 'users' container in the 'mydb' database" ``` The MCP server translates this to: ```bash cd /mydb/users query "SELECT * FROM c" ``` ### Example 3: Data analysis ``` "Count documents by status in the users container and show me the breakdown" ``` The MCP server executes: ```bash query "SELECT c.status, COUNT(*) as count FROM c GROUP BY c.status" ``` ## Authentication with MCP The MCP server uses the same authentication as Cosmos DB Shell: - **Entra ID** (Recommended) - Authenticates using Azure identity - Most secure method - Requires appropriate RBAC roles - **Managed Identity** (Production) - Automatically uses VM or App Service managed identity - Best for Azure-hosted applications - Requires identity to have Cosmos DB permissions - **Account Key** (Development) - Uses account key from connection string - Quick for testing - Less secure, avoid in production ## Security considerations ### MCP server security best practices - **Local Binding Only** (Default) ```json "cosmosDB.shell.MCP.bindToLocalhost": true ``` - Restricts MCP server to localhost - Prevents remote access - **Recommended**: Keep this enabled - **Network Isolation** - Run MCP server in isolated network - Use firewall rules to block external access - Don't expose port 6128 to public internet - **Authentication** - Use Entra ID for authentication - Implement RBAC least-privilege access - Rotate account keys regularly - **Audit and Monitoring** - Enable MCP server logging - Monitor MCP server activity - Review logs regularly for suspicious activity ### Connection security **Secure Configuration:** ```json { "cosmosDB.shell.MCP.enabled": true, "cosmosDB.shell.MCP.bindToLocalhost": true, "cosmosDB.shell.MCP.logLevel": "info" } ``` ## Troubleshooting ### MCP server won't start **Issue:** MCP server fails to start **Solutions:** 1. Check port availability: ```bash # Windows netstat -ano | findstr 6128 # macOS/Linux lsof -i :6128 ``` 2. Try different port: ```json "cosmosDB.shell.MCP.port": 6129 ``` 3. Check firewall settings 4. Review VS Code output panel for error messages ### Connection refused **Issue:** AI client can't connect to MCP server **Solutions:** 1. Verify MCP is enabled and started 2. Check correct port number (default: 6128) 3. Ensure localhost binding is enabled 4. Check firewall allows localhost connections ### Authentication failures **Issue:** MCP server can't authenticate to Cosmos DB **Solutions:** 1. Verify Cosmos DB Shell authentication works: ```bash cosmosdbshell ``` 2. Check Entra ID permissions 3. Verify managed identity has correct roles 4. Test with account key in development ### Performance issues **Issue:** MCP server is slow or unresponsive **Solutions:** 1. Reduce `maxConnections` if too many requests: ```json "cosmosDB.shell.MCP.maxConnections": 5 ``` 2. Increase timeout for slow queries: ```json "cosmosDB.shell.MCP.timeout": 60000 ``` 3. Check network connectivity 4. Monitor system resources (CPU, memory, disk) ### Port already in use **Issue:** Port 6128 is already in use **Solutions:** 1. Find and stop the process using port: ```bash # Windows netstat -ano | findstr 6128 taskkill /PID /F # macOS/Linux lsof -i :6128 kill -9 ``` 2. Change MCP port: ```json "cosmosDB.shell.MCP.port": 6129 ``` ## View MCP logs ### Enable debug logging ```json { "cosmosDB.shell.MCP.logLevel": "debug" } ``` ### Access logs Logs are displayed in VS Code Output panel: 1. Open Output panel (View > Output) 2. Select "Cosmos DB Shell" from dropdown 3. Review MCP server logs ## Stop MCP server ### In VS Code 1. Open command palette (Ctrl+Shift+P / Cmd+Shift+P) 2. Type "Cosmos DB: Stop MCP Server" 3. Press Enter ### From command line ```bash # Kill the MCP server process # The shell will exit when you type: exit ``` ## Advanced scenarios ### MCP with multiple Cosmos DB accounts Create separate MCP instances for each account: ```json { "cosmosDB.shell.MCP.enabled": true, "cosmosDB.shell.MCP.port": 6128, "cosmosDB.shell.MCP.accounts": [ { "name": "production", "endpoint": "https://prod.documents.azure.com:443/", "port": 6128 }, { "name": "staging", "endpoint": "https://staging.documents.azure.com:443/", "port": 6129 } ] } ``` ### MCP with custom AI agents Integrate MCP with custom AI agents: ```python 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) ``` ## AI tools Use these actions to plan your Shell MCP configuration. For documentation-only retrieval, use the [Microsoft Learn MCP server](/en-us/training/support/mcp), not the Shell MCP server. For a compact guide index, use the [Shell documentation index (`llms.txt`)](llms.txt). The index doesn't change crawler permissions or guarantee retrieval. Shell MCP requires separate setup and can read or change data under the configured permissions, so review tool calls before approving them. Don't share credentials or sensitive data. > > **[Connect your AI agent](/en-us/azure/cosmos-db/shell/model-context-protocol-setup#enable-mcp-server)** Follow the Shell MCP configuration steps in this article. > > **[Read as Markdown](/en-us/azure/cosmos-db/shell/model-context-protocol-setup?accept=text/markdown)** Open a text version to copy into your assistant. > > **[Ask ChatGPT](https://chatgpt.com/?hint=search&q=Read%20https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fazure%2Fcosmos-db%2Fshell%2Fmodel-context-protocol-setup%20and%20help%20me%20plan%20Shell%20MCP%20setup.%20Explain%20authentication%20and%20tool%20permissions.%20Cite%20the%20source%20and%20state%20if%20you%20cannot%20access%20it.)** Plan configuration, authentication, and tool permissions. > > **[Ask Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fazure%2Fcosmos-db%2Fshell%2Fmodel-context-protocol-setup%20and%20help%20me%20plan%20Shell%20MCP%20setup.%20Explain%20authentication%20and%20tool%20permissions.%20Cite%20the%20source%20and%20state%20if%20you%20cannot%20access%20it.)** Plan configuration, authentication, and tool permissions. ChatGPT and Claude receive only the public article URL and a starter prompt. You might need to sign in. If retrieval fails, copy the Markdown text. These links don't configure database access.