[Doc Gap] cosmos_database_container_item_vector-search — `--openai-endpoint` trusted-domain constraint not documented after PR #2895

[github-actions]

Documentation Gap

Server: Azure.Mcp.Server
Tool directory: tools/Azure.Mcp.Tools.Cosmos
Triggered by: commit bb0f8ab / PR #2895 by @vcolin7
Changed files:

• tools/Azure.Mcp.Tools.Cosmos/src/Commands/Item/ItemVectorSearchCommand.cs
• tools/Azure.Mcp.Tools.Cosmos/src/Services/CosmosService.cs

What Changed

PR #2895 added Azure OpenAI endpoint validation to the cosmos_database_container_item_vector-search tool. The --openai-endpoint parameter now performs a strict allowlist check before any service call:

• The endpoint must use HTTPS (HTTP is rejected with 400).
• The endpoint hostname must be a trusted Azure first-party domain: *.openai.azure.com, *.cognitiveservices.azure.com, *.services.ai.azure.com, or their US Government / China sovereign cloud equivalents.
• Any endpoint that does not match a trusted Azure cloud domain is rejected with a 400 Bad Request before the service is called.

Previously the parameter accepted any URI value; tests used `(aoai.example/redacted) as a placeholder, which would now be rejected.

Gaps Found

• The azmcp-commands.md description for azmcp cosmos database container item vector-search says only "Provide --openai-endpoint and --embedding-deployment" with no mention of the trusted-domain or HTTPS requirements. Users who supply a non-Azure endpoint (e.g. an on-premises proxy or a custom URL) will receive a cryptic 400 error with no guidance from the docs.
• The parameter placeholder --openai-endpoint (endpoint) gives no hint that the value is restricted; it should indicate a trusted Azure OpenAI or AI Foundry endpoint (e.g. --openai-endpoint (azure-openai-endpoint)), and the comment block should note the HTTPS + trusted-domain constraint.

Files to Update

• servers/Azure.Mcp.Server/docs/azmcp-commands.md

Context

Current documentation comment block (line ~114453):

# Vector similarity search against a Cosmos DB container. Provide --search-text plus --openai-endpoint and
# --embedding-deployment; the tool generates the query vector via Azure OpenAI and runs the search against the
# configured vector index. Optionally, provide --embedding-dimensions to request a specific number for models that
# support custom dimensions like "text-embedding-3-small" or "text-embedding-3-large". Optionally pass
# --properties-to-select to project specific fields; when omitted the full document is returned with the vector
# property stripped so the embedding doesn't bloat the response. Requires a vector index on the vector property.
# ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ❌ LocalRequired
azmcp cosmos database container item vector-search --subscription <subscription> \
                                                   --account <account> \
                                                   --database <database> \
                                                   --container <container> \
                                                   --vector-property <vector-property> \
                                                   --search-text "free-form text" \
                                                   --openai-endpoint <endpoint> \
                                                   --embedding-deployment <deployment> \
                                                   [--properties-to-select <p1,p2,...>] \
                                                   [--count 10] \
                                                   [--embedding-dimensions <n>]

Relevant diff showing the new validation logic added in the command:

+    private static void ValidateOpenAIEndpoint(string? endpoint, System.CommandLine.Parsing.CommandResult result)
+    {
+        if (string.IsNullOrWhiteSpace(endpoint))
+        {
+            result.AddError("--openai-endpoint is required.");
+            return;
+        }
+
+        // Accept the endpoint if it is valid for any supported cloud.
+        foreach (var cloud in s_openAIEndpointClouds)
+        {
+            foreach (var serviceType in s_openAIEndpointServiceTypes)
+            {
+                try
+                {
+                    EndpointValidator.ValidateAzureServiceEndpoint(endpoint, serviceType, cloud);
+                    return;
+                }
+                catch (Exception ex) when (ex is SecurityException or ArgumentException) { }
+            }
+        }
+
+        result.AddError(
+            $"The provided Azure OpenAI endpoint is not a trusted Azure OpenAI, Cognitive Services, or AI Foundry endpoint for the configured Azure cloud. The value '{endpoint}' is not allowed.");
+    }

📐 Implementation Guide

This section contains step-by-step instructions for a coding agent to implement the changes described above.

Step 1: Modify files

File: servers/Azure.Mcp.Server/docs/azmcp-commands.md
Action: Edit the Cosmos vector-search command comment block to:

1. Update the --openai-endpoint placeholder from <endpoint> to <azure-openai-endpoint> to signal it is not a generic URL.
2. Add a note in the comment block stating that --openai-endpoint must be a trusted Azure first-party HTTPS endpoint.

Replace the current block:

# Vector similarity search against a Cosmos DB container. Provide --search-text plus --openai-endpoint and
# --embedding-deployment; the tool generates the query vector via Azure OpenAI and runs the search against the
# configured vector index. Optionally, provide --embedding-dimensions to request a specific number for models that
# support custom dimensions like "text-embedding-3-small" or "text-embedding-3-large". Optionally pass
# --properties-to-select to project specific fields; when omitted the full document is returned with the vector
# property stripped so the embedding doesn't bloat the response. Requires a vector index on the vector property.
# ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ❌ LocalRequired
azmcp cosmos database container item vector-search --subscription <subscription> \
                                                   --account <account> \
                                                   --database <database> \
                                                   --container <container> \
                                                   --vector-property <vector-property> \
                                                   --search-text "free-form text" \
                                                   --openai-endpoint <endpoint> \
                                                   --embedding-deployment <deployment> \
                                                   [--properties-to-select <p1,p2,...>] \
                                                   [--count 10] \
                                                   [--embedding-dimensions <n>]

With:

# Vector similarity search against a Cosmos DB container. Provide --search-text plus --openai-endpoint and
# --embedding-deployment; the tool generates the query vector via Azure OpenAI and runs the search against the
# configured vector index. Optionally, provide --embedding-dimensions to request a specific number for models that
# support custom dimensions like "text-embedding-3-small" or "text-embedding-3-large". Optionally pass
# --properties-to-select to project specific fields; when omitted the full document is returned with the vector
# property stripped so the embedding doesn't bloat the response. Requires a vector index on the vector property.
# --openai-endpoint must be a trusted Azure first-party HTTPS endpoint on one of the following domains:
#   *.openai.azure.com, *.cognitiveservices.azure.com, *.services.ai.azure.com
# (and their US Government / China sovereign cloud equivalents). HTTP endpoints and non-Azure domains are rejected.
# ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ❌ LocalRequired
azmcp cosmos database container item vector-search --subscription <subscription> \
                                                   --account <account> \
                                                   --database <database> \
                                                   --container <container> \
                                                   --vector-property <vector-property> \
                                                   --search-text "free-form text" \
                                                   --openai-endpoint <azure-openai-endpoint> \
                                                   --embedding-deployment <deployment> \
                                                   [--properties-to-select <p1,p2,...>] \
                                                   [--count 10] \
                                                   [--embedding-dimensions <n>]

Step 2: Verify documentation structure

Verify the updated servers/Azure.Mcp.Server/docs/azmcp-commands.md still follows the expected format — the Cosmos DB section should remain inside ## Azure Cosmos DB Operations with a single fenced bash code block containing all cosmos commands.

Step 3: Validate

Run these commands in order:

1. dotnet build servers/Azure.Mcp.Server/ — confirms the server project compiles cleanly
2. dotnet build tools/Azure.Mcp.Tools.Cosmos/src/ — confirms the affected toolset compiles
3. dotnet test tools/Azure.Mcp.Tools.Cosmos/tests/Azure.Mcp.Tools.Cosmos.Tests/ --filter "TestType!=Live" — runs unit tests for the Cosmos toolset
4. .\eng\common\spelling\Invoke-Cspell.ps1 — checks spelling in the modified documentation

Next Steps

Tip

Ready for automated implementation? Assign this issue to @copilot to have Copilot coding agent implement the changes described in the Implementation Guide above

Generated by Documentation Updater · ● 10.8M · ◷