---
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: Configure the local Azure Cosmos DB Shell MCP server, connect compatible AI clients over HTTP, and understand tool permissions and pagination.
ms.collection:
- ce-skilling-ai-copilot
ms.topic: how-to
ms.update-cycle: 180-days
ms.date: 2026-11-05T00: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-11-17T19:52: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/16c9484b7ce2c37b491a4022345ffba8598ff09f/azure/cosmos-db/shell/model-context-protocol-setup.md
git_commit_id: 16c9484b7ce2c37b491a4022345ffba8598ff09f
site_name: Docs
depot_name: Learn.azure-nosql
page_type: conceptual
toc_rel: ../toc.json
word_count: 1406
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
spProducts:
- https://authoring-docs-microsoft.poolparty.biz/devrel/cc82e69d-afbe-4554-9f4c-6705fc860c42
platformId: 43102c66-2267-d144-c575-f13baa9b3b8b
---

# Azure Cosmos DB Shell Model Context Protocol Setup - Azure Cosmos DB | Microsoft Learn

The optional Azure Cosmos DB Shell Model Context Protocol (MCP) server lets compatible AI clients discover and call shell tools. It runs **locally**, sharing the shell's connection, navigation, and configured identity. This isn't a Microsoft-hosted MCP endpoint.

For documentation retrieval without database access, use the [Microsoft Learn MCP server](/en-us/training/support/mcp) instead.

## Prerequisites

- [Install Azure Cosmos DB Shell](install).
- Access to an Azure Cosmos DB account, including appropriate data-plane permissions and network connectivity.
- An MCP client that supports Streamable HTTP, or legacy HTTP+SSE. Some tools require the client to support user-confirmation requests.
- Review which data your AI client sends to its model provider before allowing tool calls.

## Enable MCP server

Start the shell from your operating-system terminal:

```bash
cosmosdbshell --mcp
```

The default port is `6128`. To select a different local port:

```bash
cosmosdbshell --mcp 6129
```

Inside that shell, connect to the intended account and verify the account-root metadata:

```bash
connect https://<account-name>.documents.azure.com/ --tenant=<tenant-id>
info --format=json
```

Replace the account name and tenant ID, complete sign-in, and confirm the returned `accountId` and `uri`. MCP doesn't grant account permissions or bypass network rules.

The server supports these transports on the same port:

| Transport | Default endpoint |
| --- | --- |
| Streamable HTTP, preferred | `http://127.0.0.1:6128/` |
| Legacy HTTP+SSE | `http://127.0.0.1:6128/sse` |

Use the port selected at startup. The server is loopback-bound with host and origin validation. Connect only trusted local clients; don't expose the endpoint through public listeners, tunnels, or port forwarding.

The shell serves HTTP MCP, not stdio. Don't configure an MCP client to launch `cosmosdbshell --mcp` as a stdio server.

## Connect from Visual Studio Code

Choose extension-managed registration or a manually configured HTTP client. Don't register both for the same shell unless you intend to expose duplicate tool sets.

### Extension-managed registration

1. Install the **Azure Cosmos DB** extension.
2. Open **Settings** and enable `cosmosDB.shell.MCP.enabled`.
3. Optionally change `cosmosDB.shell.MCP.port` from its default of `6128`.
4. Run **Launch Azure Cosmos DB Shell** from the **Command Palette**.
5. Complete installation or connection prompts and verify the account in the launched shell.
6. Use **MCP: List Servers** to locate the extension-registered **Azure Cosmos DB Shell** server and start its client connection if prompted.
7. Inspect the discovered tools before approving their use.

If the shell was already running without MCP, exit it and launch a new shell after enabling the setting. Changing a setting doesn't retrofit a server into the existing process.

The supported shell settings are:

| Setting | Default | Purpose |
| --- | --- | --- |
| `cosmosDB.shell.path` | Empty. | Override the shell executable path. |
| `cosmosDB.shell.MCP.enabled` | `false` | Start MCP with an extension-launched shell. |
| `cosmosDB.shell.MCP.port` | `6128` | Select the extension-launched server port. |

These settings don't configure Cosmos account permissions or authentication for other clients.

### Manual HTTP configuration

If you start the shell, add its Streamable HTTP URL through **MCP: Add Server**, or use an equivalent entry in your workspace's MCP configuration:

```json
{
  "servers": {
    "cosmosdb-shell": {
      "type": "http",
      "url": "http://127.0.0.1:6128/"
    }
  }
}
```

For another MCP client, use its HTTP-server configuration format with the same URL. Client configuration schemas differ; this JSON example uses Visual Studio Code's `servers` format.

Keep the shell process running while the client uses it. To stop the local server, enter `exit` in that shell. Stopping a client connection alone doesn't necessarily stop an independently launched shell process.

## Discover and use tools

After connecting, inspect the client's tool discovery result. Shell tools use command names such as `info`, `schema`, `query`, and `print`; clients might add a server prefix.

Call tools with **structured arguments**, not literal command-line flags. For example, after verifying the account, a bounded `query` tool call can use:

```json
{
  "query": "SELECT c.id FROM c",
  "database": "MyDatabase",
  "container": "MyContainer",
  "max": 5
}
```

Replace resource names with your intended target. This JSON is the tool's arguments, not an HTTP REST request body for a `/query` endpoint. Use the MCP protocol through your client.

Equivalent interactive shell syntax is:

```bash
query "SELECT c.id FROM c" --database=MyDatabase --container=MyContainer --max=5
```

Ask your assistant to inspect the schema, select only required fields, explain proposed writes, and report actual costs and completeness from returned results.

### Shared state and paging

All clients share the interactive shell's connection and navigation. Calls are serialized, but one client's connection or navigation changes affect others. Pass explicit `database` and `container` arguments whenever supported. Don't assume the Visual Studio Code query editor shares the shell's connection.

MCP `query` and item-listing `ls` return bounded pages, defaulting to 100 items. If the result includes a non-null `continuationToken`, pass it unchanged as the next call's `continuation` argument with the same options. That argument is MCP-only; the interactive shell doesn't accept a continuation-token flag.

A non-null token, `resultIncomplete: true`, or `limitReached` indicates that results aren't complete. A null token with `resultIncomplete: true` means the truncated result can't be resumed; narrow the request or increase its bound instead of reporting it as complete.

## Understand tool access and confirmation

The shell uses the identity and permissions of its configured connection. Separate Azure Cosmos DB data permissions from management-plane permissions, and grant only the actions needed for the task.

| Capability | MCP behavior |
| --- | --- |
| Diagnostics, schema discovery, queries, and point reads | Available through their discovered tool schemas. Reads and diagnostic probes can consume RUs. |
| Transactional batches | Only one-shot `batch run`; stateful subcommands remain interactive-only. |
| Independent bulk operations | `bulk run`, `bulk patch`, and `bulk delete`; stateful jobs remain interactive-only. |
| Stored procedures, user-defined functions, and triggers | `sproc`, `udf`, and `trigger` aren't exposed through MCP. |
| Change-feed streaming | `watch` / `tail` isn't exposed through MCP. |

Important

Shell MCP can change or delete resources and data under the configured permissions. Use a least-privilege identity, review requested tools, and back up important data before destructive operations. Don't share credentials or sensitive documents in prompts.

Destructive commands such as `delete`, `rm`, `rmcon`, and `rmdb` require explicit user confirmation. A force argument doesn't bypass that MCP confirmation. Bulk writes also require confirmation; a bulk dry run without `save` doesn't, but saving a plan writes a local file and requires confirmation.

If the client can't present the required confirmation, or you decline it, the tool fails without executing. Don't bypass that result with another command or execution route. A pending approval is invalidated when the connection or navigation changes, even if it later returns to its former location; re-verify the target before requesting approval again.

For exact-item deletion, retain the same database, container, ID, complete typed partition key, and actual preview ETag between review and execution. Follow the [safe deletion procedure](command-reference#delete-an-exact-item-safely).

MCP commands can be recorded in replayable shell history, including connection strings. Treat history as sensitive and prefer Microsoft Entra authentication.

## Troubleshoot MCP connections

Distinguish a missing executable, a server-start failure, a client transport or configuration error, and an account-connection error before changing your environment.

- **Server unavailable.** Confirm the shell process is running with `--mcp`, or relaunch it after enabling the extension's MCP setting.
- **Wrong transport.** Use the root URL for Streamable HTTP or `/sse` for a legacy SSE client. Verify MCP initialization and tool discovery with the client; don't use a `/health` endpoint.
- **Port conflict.** Select another port, such as `6129`, and update the client URL to match. Don't terminate an unrelated process to free the port.
- **No account access.** In the shell, run `doctor --no-update-check`, `whoami`, and a scoped `can-i query` probe. Review authentication, data permissions, and network restrictions separately.
- **Slow or incomplete results.** Narrow the query, specify a positive bound, and inspect pagination. Calls share one execution gate; increasing parallel requests doesn't make them execute concurrently.
- **Legacy SSE overload.** The server limits outstanding legacy SSE requests. On HTTP `429`, honor `Retry-After` and reduce outstanding calls. This admission limit doesn't apply to Streamable HTTP.

## 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&amp;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.