PowerPlatform MCP

Instructions

Implementation Reference

• src/services/flow-service.ts:1065-1110 (handler)

  Main implementation of cancelFlowRun that checks if flow is in terminal state, calls the Flow API to cancel, and returns the result with previous status

  /**
   * Cancel a running or waiting flow run
   */
  async cancelFlowRun(flowId: string, runId: string): Promise<CancelFlowRunResult> {
    try {
      const environmentId = await this.getEnvironmentId();
      const token = await this.client.getManagementToken();
  
      const runDetails = await this.getFlowRunDetails(flowId, runId) as Record<string, unknown>;
      const status = (runDetails.status as string) || '';
  
      const terminalStates = ['Succeeded', 'Failed', 'Cancelled'];
      if (terminalStates.includes(status)) {
        throw new Error(`Cannot cancel flow run - already in terminal state: ${status}`);
      }
  
      const url = `https://api.flow.microsoft.com/providers/Microsoft.ProcessSimple/environments/${environmentId}/flows/${flowId}/runs/${runId}/cancel?api-version=2016-11-01`;
  
      await axios.post(url, {}, {
        headers: {
          Authorization: `Bearer ${token}`,
          Accept: 'application/json',
        },
      });
  
      return {
        success: true,
        flowId,
        runId,
        previousStatus: status,
      };
    } catch (error: unknown) {
      const err = error as {
        response?: {
          status?: number;
          statusText?: string;
          data?: { error?: unknown };
        };
        message?: string;
      };
      const errorDetails = err.response?.data?.error || err.response?.data || err.message;
      throw new Error(
        `Failed to cancel flow run: ${err.message} - ${JSON.stringify(errorDetails)}`
      );
    }
  }

• src/tools/flow-tools.ts:276-321 (registration)

  Registration of the 'cancel-flow-run' tool with the MCP server, including input/output schema and handler function that calls the flow service

  // Cancel Flow Run
  server.registerTool(
    "cancel-flow-run",
    {
      title: "Cancel Flow Run",
      description: "Cancel a running or waiting flow run. Cannot cancel flows already in a terminal state (Succeeded, Failed, Cancelled).",
      inputSchema: {
        flowId: z.string().describe("The workflow ID (GUID)"),
        runId: z.string().describe("The flow run ID"),
        environment: z.string().optional().describe("Environment name (e.g. DEV, UAT). Uses default if omitted."),
      },
      outputSchema: z.object({
        success: z.boolean(),
        flowId: z.string(),
        runId: z.string(),
        previousStatus: z.string(),
      }),
    },
    async ({ flowId, runId, environment }) => {
      try {
        const ctx = registry.getContext(environment);
        const service = ctx.getFlowService();
        const result = await service.cancelFlowRun(flowId, runId);
  
        return {
          structuredContent: result,
          content: [
            {
              type: "text",
              text: `Flow run cancelled successfully.\nFlow: ${flowId}\nRun: ${runId}\nPrevious status: ${result.previousStatus}`,
            },
          ],
        };
      } catch (error: any) {
        console.error("Error cancelling flow run:", error);
        return {
          content: [
            {
              type: "text",
              text: `Failed to cancel flow run: ${error.message}`,
            },
          ],
        };
      }
    }
  );

• src/services/flow-service.ts:57-63 (helper)

  TypeScript interface defining the shape of the CancelFlowRunResult returned by the cancelFlowRun method

  export interface CancelFlowRunResult {
    [key: string]: unknown;
    success: boolean;
    flowId: string;
    runId: string;
    previousStatus: string;
  }