ryanmichaeljames/pipe-dream-mcp

Model Context Protocol (MCP) server for Microsoft Dataverse and Azure DevOps (coming soon).

Overview

PipeDream MCP enables AI agents (like GitHub Copilot) to interact with Microsoft Dataverse and Power Platform using Azure CLI authentication. This MCP server provides secure access to Dataverse data and Power Platform management through a standardized protocol interface.

Key Features:

• Dataverse operations - Query, retrieve, metadata with full OData support
• Power Automate flow management - Query, activate, and deactivate cloud flows
• Power Platform environment management - List environments, get settings, view operations history
• Azure CLI authentication - Secure token-based auth with automatic caching and refresh
• Flexible configuration - Inline arguments or JSON config files
• Safety controls - Opt-in flags for write and delete operations (default: disabled)
• File-based logging - Per-environment log files with automatic 30-day cleanup
• AI-friendly - Enhanced tool descriptions and guidance for better agent behavior
• Production-ready - Comprehensive error handling, retry logic with exponential backoff, and input validation
• MCP protocol compliant - Implements MCP 2024-11-05 specification

Prerequisites

• .NET 10.0 SDK - Download
• Azure CLI - Install
• Azure subscription with Dataverse access
• Run az login to authenticate

Installation

Option 1: .NET Global Tool (Recommended)

# Install globally
dotnet tool install --global PipeDream.Mcp

# Verify installation
pipedream-mcp --version

# Update to latest version
dotnet tool update --global PipeDream.Mcp

Option 2: Build from Source

git clone https://github.com/ryanmichaeljames/pipe-dream-mcp.git
cd pipe-dream-mcp

# Run directly
dotnet run --project src/PipeDream.Mcp -- dataverse --dataverse-url https://your-org.crm.dynamics.com/

# Or build and publish
dotnet publish src/PipeDream.Mcp/PipeDream.Mcp.csproj -c Release -o ./publish
./publish/PipeDream.Mcp dataverse --dataverse-url https://your-org.crm.dynamics.com/

Quick Start

1. Authenticate with Azure CLI:

   az login
   

2. Configure VS Code MCP settings (%APPDATA%\Code\User\mcp.json on Windows):

   {
     "servers": {
       "pipedream": {
         "type": "stdio",
         "command": "pipedream-mcp",
         "args": [
           "dataverse",
           "--dataverse-url",
           "https://your-org.crm.dynamics.com/"
         ]
       }
     }
   }
   

3. Reload VS Code (Ctrl+Shift+P → "Developer: Reload Window")

4. Use in Copilot Chat: #pipedream What Dataverse entities are available?

Command Reference

Synopsis

pipedream-mcp <subcommand> [options]
pipedream-mcp --help
pipedream-mcp --version

Subcommands

• dataverse - Run Dataverse MCP server
• powerplatform - Run Power Platform MCP server
• azure-devops - Run Azure DevOps MCP server (coming soon)

Dataverse Subcommand

pipedream-mcp dataverse --dataverse-url <url> [options]
pipedream-mcp dataverse --config-file <path> [options]
pipedream-mcp dataverse --help

Parameters

* Either --dataverse-url or --config-file is required.

Examples

Basic usage with inline configuration:

pipedream-mcp --dataverse-url https://org.crm.dynamics.com/

Enable write operations:

pipedream-mcp --dataverse-url https://org.crm.dynamics.com/ --enable-write-operations

Enable both write and delete operations:

pipedream-mcp --dataverse-url https://org.crm.dynamics.com/ --enable-write-operations --enable-delete-operations

Using a config file:

pipedream-mcp --config-file C:/configs/prod.json

Override config file settings:

pipedream-mcp --config-file C:/configs/prod.json --enable-write-operations

Enable verbose logging for troubleshooting:

pipedream-mcp --dataverse-url https://org.crm.dynamics.com/ --verbose

Configuration File Format

Create JSON config files for reusable environment settings:

{
  "dataverse": {
    "url": "https://your-org.crm.dynamics.com",
    "apiVersion": "v9.2",
    "timeout": 30,
    "enableWriteOperations": false,
    "enableDeleteOperations": false
  }
}

Note: Command-line parameters always override config file values.

Logging

PipeDream MCP uses file-based logging following MCP protocol best practices (stderr reserved for fatal errors only).

Log Files:

• Location: {AppDirectory}/logs/pipedream-mcp-{subcommand}-{orgname}-{yyyyMMdd}.log
• Example: logs/pipedream-mcp-dataverse-orgname-20251121.log
• One log file per subcommand/organization per day
• Automatic cleanup after 30 days

Log Levels:

• Default (Information): Server lifecycle, auth status, connectivity tests
• Verbose (Debug): All requests/responses, detailed message content

Usage:

# Information logging (default)
pipedream-mcp dataverse --dataverse-url https://org.crm.dynamics.com/

# Debug logging (verbose)
pipedream-mcp dataverse --dataverse-url https://org.crm.dynamics.com/ --verbose

Log Path Display: On startup, the log file path is displayed on stderr:

Logs: C:/path/to/logs/pipedream-mcp-dataverse-orgname-{yyyyMMdd}.log

VS Code MCP Configuration

Add to your VS Code MCP settings file:

Settings file location:

• Windows: %APPDATA%\Code\User\mcp.json
• macOS: ~/Library/Application Support/Code/User/mcp.json
• Linux: ~/.config/Code/User/mcp.json

Inline configuration (recommended):

{
  "servers": {
    "pipedream": {
      "type": "stdio",
      "command": "pipedream-mcp",
      "args": [
        "--dataverse-url", "https://your-org.crm.dynamics.com/",
        "--enable-write-operations"
      ]
    }
  }
}

Config file approach:

{
  "servers": {
    "pipedream-prod": {
      "type": "stdio",
      "command": "pipedream-mcp",
      "args": ["--config-file", "C:/configs/prod.json"]
    }
  }
}

Available Tools

dataverse_query

Query Dataverse entities using OData. Use entity plural names (e.g., 'accounts', 'contacts', 'workflows').

Parameters:

• entity (required) - Entity plural name: 'accounts', 'contacts', 'workflows', 'solutions', etc.
• select (optional) - Field names to return. Example: ['name', 'emailaddress1', 'createdon']
• filter (optional) - OData filter. Examples: "statecode eq 0", "name eq 'Contoso'", "contains(name, 'test')"
• orderby (optional) - Order results by field(s). Examples: "createdon desc", "name asc", "modifiedon desc,name asc"
• top (optional) - Max records (default: 50, max: 5000). Use 5-10 for specific searches.
• count (optional) - Include total count of matching records (default: true). Returns @odata.count in response.
• maxpagesize (optional) - Maximum records per page. When set, Dataverse returns @odata.nextLink for pagination. Do not use with top - they conflict.

Pagination:

• Use maxpagesize (e.g., 10, 50, 100) to enable server-driven pagination
• Important: Cannot use top and maxpagesize together - they conflict
• Dataverse returns @odata.nextLink when more pages exist
• Follow the @odata.nextLink URL to get subsequent pages (requires HTTP GET with auth headers)
• Each page includes the same @odata.count (total records) and a new @odata.nextLink

Parameter Usage:

• Use top when you want to limit total results (e.g., "get me 10 contacts")
• Use maxpagesize when you need pagination (e.g., "page through all contacts, 50 at a time")
• No default page size - if neither parameter is set, top defaults to 50 records

Example 1: Query recently created contacts (limit to 10 records)

{
  "entity": "contacts",
  "select": ["fullname", "emailaddress1", "createdon"],
  "orderby": "createdon desc",
  "top": 10
}

Example 2: Enable pagination with small page size

{
  "entity": "contacts",
  "select": ["contactid", "fullname"],
  "orderby": "fullname asc",
  "maxpagesize": 10
}

Response with pagination:

{
  "@odata.context": "...",
  "@odata.count": 247,
  "@odata.nextLink": "https://org.crm.dynamics.com/api/data/v9.2/contacts?$skiptoken=...",
  "value": [
    {"contactid": "...", "fullname": "..."}
  ]
}

dataverse_query_nextlink

Fetch the next page of results using the @odata.nextLink URL from a previous query.

Parameters:

• nextlink (required) - The full @odata.nextLink URL from the previous response
• maxpagesize (optional) - Records per page, should match original query for consistent page sizes (e.g., 10, 50, 100)

Example: Get page 2 with consistent page size

{
  "nextlink": "https://org.crm.dynamics.com/api/data/v9.2/contacts?$select=contactid,fullname&$skiptoken=...",
  "maxpagesize": 10
}

Pagination flow:

1. Query with maxpagesize: dataverse_query → Get page 1 + @odata.nextLink
2. Use nextLink with same maxpagesize: dataverse_query_nextlink → Get page 2 + new @odata.nextLink
3. Repeat step 2 until no @odata.nextLink in response (last page)

Important: Pass the same maxpagesize value to all pages for consistent results per page.

dataverse_query_flows

Query Power Automate cloud flows with optimized filtering and human-readable output.

Parameters:

• solutionUniqueName (optional) - Filter flows by solution unique name
• solutionId (optional) - Filter flows by solution GUID
• filter (optional) - OData filter for advanced queries (e.g., "name eq 'FlowName'", "contains(name, 'Test')")
• select (optional) - Additional fields beyond core set (clientdata, primaryentity, etc.)
• top (optional) - Limit total records (default: 50, max: 5000). Do not use with maxpagesize
• orderby (optional) - Order results by field(s) (e.g., "createdon desc", "name asc")
• count (optional) - Include total count (default: true). Returns @odata.count in response
• maxpagesize (optional) - Records per page for pagination (e.g., 10, 50, 100). Enables @odata.nextLink. Do not use with top

Example: Find draft flows in a solution

{
  "solutionUniqueName": "MySolution",
  "filter": "statecode eq 0",
  "top": 10
}

Example: Paginate through all flows, 5 at a time

{
  "maxpagesize": 5,
  "orderby": "createdon desc"
}

dataverse_retrieve

Retrieve a single Dataverse record by ID. Use entity plural names.

Parameters:

• entity (required) - Entity plural name: 'accounts', 'contacts', 'workflows', etc.
• id (required) - Record GUID
• select (optional) - Field names to return (optional). Example: ['name', 'createdon']

Example: Get specific account by ID

dataverse_metadata

Get Dataverse entity metadata including available entities and their attributes.

Parameters:

• entity (optional) - Entity plural name for specific metadata. If omitted, returns all entities.

Example: Get schema information for workflows entity

dataverse_activate_flow

Activate a Power Automate flow. Requires --enable-write-operations flag.

Parameters:

• workflowId (required) - Workflow GUID to activate
• validateConnectionReferences (optional) - Check connection references before activating (default: false)

Example: Activate a flow with connection validation

dataverse_deactivate_flow

Deactivate a Power Automate flow (set to Draft state). Requires --enable-write-operations flag.

Parameters:

• workflowId (required) - Workflow GUID to deactivate

Example: Deactivate a flow for maintenance

Power Platform Subcommand

The Power Platform subcommand provides environment management capabilities for Power Platform administrators.

Usage

pipedream-mcp powerplatform --config-file <path> [options]
pipedream-mcp powerplatform --help

Note: Power Platform subcommand requires a config file (no inline URL option).

Configuration

Create a config file with the powerplatform section:

{
  "powerplatform": {
    "apiVersion": "2022-03-01-preview",
    "timeout": 30
  },
  "logging": {
    "level": "info"
  }
}

Config file can include both Dataverse and Power Platform sections:

{
  "dataverse": {
    "url": "https://your-org.crm.dynamics.com/",
    "apiVersion": "v9.2",
    "timeout": 30
  },
  "powerplatform": {
    "apiVersion": "2022-03-01-preview",
    "timeout": 30
  }
}

Power Platform Tools

powerplatform_environmentmanagement_list_environments

List all Power Platform environments the authenticated user has access to.

Parameters: None

Returns: Environment details including ID, name, type, region, and state.

Example: Discover all environments

{}

powerplatform_environmentmanagement_get_environment_settings

Get settings and feature flags for a specific environment.

Parameters:

• environmentId (required) - Environment GUID (use list_environments to discover)
• select (optional) - Comma-separated list of setting names
• top (optional) - Maximum number of settings to return

Example: Get all settings for an environment

{
  "environmentId": "12345678-1234-1234-1234-123456789012"
}

powerplatform_environmentmanagement_list_environment_operations

List lifecycle operations (create, update, delete, backup, restore) for an environment.

Parameters:

• environmentId (required) - Environment GUID
• limit (optional) - Maximum operations per page
• continuationToken (optional) - Token for next page

Example: View recent operations

{
  "environmentId": "12345678-1234-1234-1234-123456789012",
  "limit": 10
}

powerplatform_environmentmanagement_get_operation

Get detailed information about a specific operation.

Parameters:

• operationId (required) - Operation GUID (from list_environment_operations)

Example: Check operation status

{
  "operationId": "87654321-4321-4321-4321-210987654321"
}

Logging

Power Platform logging uses: logs/pipedream-mcp-powerplatform-{yyyyMMdd}.log

This single log file applies to all environments since Power Platform tools work across all environments the user has access to.

VS Code Configuration

{
  "servers": {
    "pipedream-powerplatform": {
      "type": "stdio",
      "command": "pipedream-mcp",
      "args": ["powerplatform", "--config-file", "C:/configs/prod.json"]
    }
  }
}

Contributing

Contributions welcome! Please see the wiki for detailed development documentation.

License

Apache 2.0 - See file for details.

References

• MCP Specification
• Dataverse Web API
• Azure.Identity Library
• GitHub Copilot MCP Support