The Azure Cosmos DB extension can install and launch Azure Cosmos DB Shell in an integrated terminal. It can also register the shell's optional local MCP server for compatible AI features.
The shell is distinct from the extension's NoSQL query editor. Don't assume the two share a connection, database, or container.
Prerequisites
- Install a supported version of Visual Studio Code.
- Install Azure Cosmos DB, published by Microsoft, with extension ID
ms-azuretools.vscode-cosmosdb. - Have an Azure Cosmos DB account, appropriate permissions, and network access from your machine.
You can use an extension-managed shell or an existing installation. For other installation methods, see Install Azure Cosmos DB Shell.
Launch the shell
Open the Command Palette with Ctrl+Shift+P on Windows or Linux, or Cmd+Shift+P on macOS.
Run Launch Azure Cosmos DB Shell. The command ID is
cosmosDB.launchCosmosDBShell.Complete the installation or repair flow if prompted.
In the new shell terminal, run:
version help
If you launch from an account context, inspect the resulting connection before using it. To connect explicitly, replace the account name and tenant ID and run:
connect https://<account-name>.documents.azure.com/ --tenant=<tenant-id>
info --format=json
Complete sign-in and verify accountId and uri at the account root. pwd shows navigation, not account identity.
Inspect and query a container
Inside the shell, list databases and substitute actual resource names in the following commands:
ls
ls --database=MyDatabase
schema --database=MyDatabase --container=MyContainer --sample=20
query "SELECT TOP 5 c.id FROM c" --database=MyDatabase --container=MyContainer --max=5
Use explicit scopes and a positive query bound. These reads consume RUs.
For deeper inspection, use the command reference to find diagnostics, point reads, query explanation, batches, bulk operations, import/export, and policy commands.
Configure shell settings
Open Settings and search for cosmosDB.shell, or edit your settings JSON.
| Setting | Default | Description |
|---|---|---|
cosmosDB.shell.path |
Empty. | Full path to a custom shell executable instead of an extension-managed copy. |
cosmosDB.shell.MCP.enabled |
false |
Enable local MCP when the extension launches the shell. |
cosmosDB.shell.MCP.port |
6128 |
Port for that MCP server. |
For example:
{
"cosmosDB.shell.MCP.enabled": true,
"cosmosDB.shell.MCP.port": 6128
}
An optional Windows executable path must escape backslashes in JSON:
{
"cosmosDB.shell.path": "C:\\Tools\\CosmosDBShell\\cosmosdbshell.exe"
}
Use your actual executable path. Exit and relaunch the shell after changing launch settings.
Enable local AI integration
- Review the Shell MCP setup and permissions.
- Enable
cosmosDB.shell.MCP.enabledand select an available port. - Run Launch Azure Cosmos DB Shell and verify its account connection.
- Open MCP: List Servers, locate the extension-registered Azure Cosmos DB Shell server, and start its client connection if prompted.
- Inspect the discovered tools and approve only the access needed for your task.
The server uses Streamable HTTP at http://127.0.0.1:6128/, with legacy SSE at /sse. Use the selected port if you changed it. The extension's MCP settings apply to extension-launched shells, not independently launched processes.
MCP clients share the shell's connection and navigation, and can operate with its permissions. Keep the server local, use a least-privilege identity, and review destructive confirmations.
Export a bounded selection
For a local JSON-array file that import can read directly:
export sample-ids.json --database=MyDatabase --container=MyContainer --query="SELECT c.id FROM c" --max=5
This example intentionally exports only IDs. It isn't a full-fidelity backup or a complete migration file. Use full documents, the intended scope, and an appropriate bound for a reviewed data-copy workflow. See Import and export.
Use built-in filter for JSON transformations or an installed jq for features beyond the built-in subset. To inspect sampled field metadata as a table:
schema --database=MyDatabase --container=MyContainer --fields-only | filter '.fields' | ftab
Troubleshoot editor integration
- Launch command missing. Confirm that the Microsoft Azure Cosmos DB extension is installed and enabled for the current VS Code environment.
- Wrong executable or old commands. Check
cosmosDB.shell.pathand runversionandhelpin the launched terminal. An extension-managed shell can differ from the executable on your terminal'sPATH. - MCP server unavailable. Enable the supported MCP setting, exit an existing non-MCP shell, and relaunch it. Use a different port if the selected one is already in use.
- Database access fails. Run
doctor --no-update-check,whoami, and a scopedcan-i queryinside the shell. Separate credential, permission, and network problems before changing settings. - A command is waiting. Check for an authentication or confirmation prompt. Use Ctrl+C to cancel a command when appropriate; inspect partial write outcomes before retrying.
For protocol configuration and paging, see Shell MCP setup. For shell diagnostics, see the troubleshooting guide.
AI tools
Use these actions to discuss Shell integration in Visual Studio Code.
For documentation-only retrieval, use the Microsoft Learn MCP server. For a compact guide index, use the Shell documentation index (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
Configure Shell MCP for authenticated database operations.Read as Markdown
Open a text version to copy into your assistant.Ask ChatGPT
Get guidance for your extension workflow.Ask Claude
Get guidance for your extension workflow.
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.