mcp_execute_query

Execute SQL queries on CosmosDB containers to retrieve and analyze document data with parameter support and cross-partition capabilities.

Instructions

Execute a SQL query against a CosmosDB container

Input Schema

TableJSON Schema

Name	Required	Description
`container_id`	Yes	The ID of the container to query
`query`	Yes	The SQL query to execute
`parameters`	No	Optional parameters for the query as key-value pairs
`max_items`	No	Maximum number of items to return
`enable_cross_partition`	No	Whether to enable cross-partition queries

Implementation Reference

src/tools/dataOperations.ts:7-46 (handler)

Core implementation of the mcp_execute_query tool handler. Executes SQL queries on CosmosDB containers, supports parameters, limits results, and returns documents with query statistics.

export const mcp_execute_query = async (args: { 
  container_id: string; 
  query: string; 
  parameters?: Record<string, any>;
  max_items?: number;
  enable_cross_partition?: boolean;
}): Promise<ToolResult<{ documents: any[]; stats: QueryStats }>> => {
  const { container_id, query, parameters, max_items = 100, enable_cross_partition = true } = args;
  console.log('Executing mcp_execute_query with:', args);

  try {
    const container = getContainer(container_id);
    const startTime = Date.now();

    // Prepare query spec
    const querySpec = {
      query,
      parameters: parameters ? Object.entries(parameters).map(([name, value]) => ({ name: `@${name}`, value })) : []
    };

    // Execute query
    const queryIterator = container.items.query(querySpec, {
      maxItemCount: max_items
    });

    const { resources: documents, requestCharge } = await queryIterator.fetchAll();
    const executionTimeMs = Date.now() - startTime;

    const stats: QueryStats = {
      requestCharge,
      executionTimeMs,
      documentCount: documents.length
    };

    return { success: true, data: { documents, stats } };
  } catch (error: any) {
    console.error(`Error in mcp_execute_query for container ${container_id}: ${error.message}`);
    return { success: false, error: error.message };
  }
};

src/tools.ts:72-103 (schema)

Tool metadata and JSON input schema definition for mcp_execute_query, used for tool discovery and validation.

{
  name: "mcp_execute_query",
  description: "Execute a SQL query against a CosmosDB container",
  inputSchema: {
    type: "object",
    properties: {
      container_id: {
        type: "string",
        description: "The ID of the container to query"
      },
      query: {
        type: "string",
        description: "The SQL query to execute"
      },
      parameters: {
        type: "object",
        description: "Optional parameters for the query as key-value pairs"
      },
      max_items: {
        type: "number",
        description: "Maximum number of items to return",
        default: 100
      },
      enable_cross_partition: {
        type: "boolean",
        description: "Whether to enable cross-partition queries",
        default: true
      }
    },
    required: ["container_id", "query"]
  }
},

src/server.ts:63-66 (registration)

Registration of tool list handler, exposing MCP_COSMOSDB_TOOLS (including mcp_execute_query schema) for MCP tool discovery.

// @ts-ignore - Bypass TypeScript errors from the SDK's types
server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: MCP_COSMOSDB_TOOLS
}));

src/server.ts:103-105 (registration)
Dispatch/execution routing for mcp_execute_query tool call in the MCP CallToolRequest handler.
```
case 'mcp_execute_query':
    result = await toolHandlers.mcp_execute_query(input as any);
    break;
```

src/tools/types.ts:31-36 (helper)

Type definitions for QueryStats used in the tool's return type.

export interface QueryStats {
  requestCharge: number;
  executionTimeMs: number;
  documentCount: number;
  indexHitRatio?: number;
}

MCP CosmosDB