azure-cosmos -samples

This MCP server collection demonstrates how to build and run Model Context Protocol (MCP) servers that interface with Azure Cosmos DB. The samples provide ready-to-run implementations in JavaScript/TypeScript, Go, Java, and Python, all designed to enable AI agents to interact with Cosmos DB through natural language prompts. The toolkit exposes capabilities such as executing document operations (create, read, update, delete), performing vector search on stored data, and discovering or inferring schema information to help agents understand the data model. To use the server, start the chosen language-specific sample and point your MCP-enabled agent at it; the server will translate natural language queries into Cosmos DB operations and return structured results suitable for downstream reasoning.

Prerequisites:

• Node.js (for the JavaScript/TypeScript samples) or the corresponding runtime for the language you choose (Go, Java, Python)
• Access to an Azure Cosmos DB account with appropriate permissions
• Git for cloning the repository (optional if you download the samples)

Installation steps:

1. Install prerequisites for your language/runtime (see below).
2. Clone the repository or download the relevant language sample folders (javascript, golang, java, python).
3. Navigate to the sample folder you want to run (e.g., javascript) and install dependencies.

Language-specific examples:

• JavaScript/TypeScript (Node.js):

  • cd javascript
  • npm install
  • Configure environment variables (see notes)
  • npm run start

• Go:

  • cd golang
  • go mod download
  • go build ./...
  • ./your-built-binary

• Java:

  • cd java
  • mvn -q -DskipTests package
  • java -jar target/your-mcp-server.jar

• Python:

  • cd python
  • python -m venv venv
  • source venv/bin/activate (Linux/macOS) or venv\Scripts\activate (Windows)
  • pip install -r requirements.txt
  • python -m your_server_module

Configuring the server typically requires environment variables (see notes). After starting, you should have a running MCP server listening on a localhost port or as configured by the sample.

Environment variables and configuration options:

• COSMOS_ENDPOINT or COSMOS_ACCOUNT_ENDPOINT: The REST endpoint for your Cosmos DB account.
• COSMOS_KEY or COSMOS_PRIMARY_KEY: Access key for the Cosmos DB account.
• COSMOS_DATABASE: Target database name within Cosmos DB.
• COSMOS_CONTAINER: Target container/collection name.
• AZURE_TENANT_ID and AZURE_CLIENT_ID / AZURE_CLIENT_SECRET (if using Entra ID authentication in samples that support it).
• Vector search settings (if applicable): VECTOR_INDEX_NAME, VECTOR_FIELD, and any custom schema metadata.
• For local testing, ensure network access to the Cosmos DB account and that firewall settings allow connections from your running server.

Common issues:

• Invalid Cosmos DB credentials or incorrect endpoint leading to authentication failures.
• Missing required environment variables for the selected runtime.
• Port conflicts or firewall rules preventing access from your agent.

Tips:

• Start with the JavaScript/TypeScript sample if you are new to MCP, as it often has straightforward configuration files and scripts.
• Review sample README in the language folder you choose for exact commands and configuration details.