[FEATURE] Minimum deployment contract: only COSMOS_ENDPOINT required; make embedding and auth settings optional

[sajeetharan]

Feature Description

Establish a minimal deployment contract for the Cosmos DB MCP Toolkit so that the only required input to run the server is the Cosmos DB account endpoint. All other settings — including OpenAI / embedding configuration and inbound MCP auth settings — should be optional and only required when the corresponding feature is used.

Problem or Use Case

The Connector Namespaces team validated the toolkit locally and asked for a minimum, well-defined "core contract" that their hosted MCP platform can target. The current appsettings.json / env-var surface mixes core Cosmos settings with embedding/OpenAI settings and Entra app-registration settings, so deployments fail or require placeholder values even when callers won't use vector/hybrid search.

The ideal minimum contract for hosted scenarios is:

COSMOS_ENDPOINT=https://<account>.documents.azure.com:443/

Authentication to Cosmos is via DefaultAzureCredential (the hosting identity's managed identity) with data-plane RBAC granted out-of-band.

Proposed Solution

1. Define and document a tiered configuration model:
   • Required: COSMOS_ENDPOINT
   • Optional (core auth — needed only when self-hosting without a gateway): AzureAd:TenantId, AzureAd:ClientId, AzureAd:Audience — see #(configurable-inbound-auth issue)
   • Optional (vector/hybrid search only): Azure OpenAI / Azure AI Foundry / OpenAI embedding settings
   • Optional (telemetry): OTEL_* — see #(otel-instrumentation issue)
2. Lazy validation: do not validate or instantiate embedding clients at startup. Validate only when a vector/hybrid-search tool is invoked, and return a clear MCP error response if embeddings aren't configured (e.g., EmbeddingsNotConfigured: configure AzureOpenAI or OpenAI settings to enable vector_search / hybrid_search).
3. Tool surface gating: at MCP tools/list time, omit vector/hybrid-search tools (or mark them as unavailable) when no embedding provider is configured, so agents don't see tools they can't call.
4. No key-based fallback for Cosmos: managed identity + data-plane RBAC only. (Confirmed with Connector Namespaces team.)
5. Startup logging: emit a single structured log line at startup summarizing which feature areas are enabled (core tools, vector search, hybrid search, auth mode, OTel exporter) so hosts can confirm the contract from logs.
6. Update README.md, docs/QUICK-START.md, and infrastructure/ parameter templates to reflect required vs optional inputs and to document the minimum deployment shape.

Example Usage

# Minimum hosted deployment (Connector Namespaces / any gateway)
COSMOS_ENDPOINT=https://<account>.documents.azure.com:443/

# Optional — enables vector_search / hybrid_search tools
AZURE_OPENAI_ENDPOINT=https://<aoai>.openai.azure.com/
AZURE_OPENAI_EMBEDDING_DEPLOYMENT=text-embedding-3-small

Alternatives Considered

• Keep all settings effectively required and document which to set to dummy values — rejected; brittle and produces misleading errors at startup.
• Require an embedding provider to be configured even for non-search workloads — rejected; vector/hybrid search is opt-in and the host shouldn't need an OpenAI account to run the server.

Context

Tracking ask from the Connector Namespaces team for onboarding the Cosmos DB MCP Toolkit to their hosted MCP platform. Related: configurable inbound auth issue, OpenTelemetry instrumentation issue.