Dataverse MCP Server
A Model Context Protocol (MCP) server for Microsoft Dataverse that enables schema operations including creating and updating tables, columns, relationships, and option sets using the Dataverse Web API.
🚀 Key Features
✅ Manage Tables & Columns - Create, update, delete, and list custom tables with all column types (String, Integer, Boolean, DateTime, Picklist, Lookup, etc.)
✅ Manage Relationships - Create One-to-Many and Many-to-Many relationships between entities with proper cascade behaviors
✅ Manage Option Sets - Create and manage global option sets with custom options, colors, and values
✅ Solution-Based Architecture - Enterprise-grade solution management with persistent context and automatic customization prefixes
✅ Security & Access Control - Complete security role management, team operations, and business unit hierarchy management
✅ WebAPI Call Generator - Generate ready-to-use HTTP requests, cURL commands, and JavaScript code for any Dataverse operation
✅ PowerPages WebAPI Generator - Generate PowerPages-specific WebAPI calls using the /_api/[logicalEntityName]
format with React examples
✅ PowerPages Configuration Management - Manage table permissions and WebAPI site settings for PowerPages Code Sites with YAML file automation
✅ Schema Export & Visualization - Export complete solution schemas to JSON with advanced filtering, then generate professional Mermaid ERD diagrams with relationship visualization
✅ Mermaid Diagram Generation - Convert exported schemas into professional Entity Relationship Diagrams with enhanced column markers, lookup target display, and unlimited table support
✅ Professional Integration - OAuth2 authentication, comprehensive error handling, and enterprise-ready deployment
✅ Production Ready - Comprehensive testing completed with 7 critical bugs found and fixed, 100% tool coverage achieved
Table of Contents
- Features
- Solution-Based Architecture
- Supported Column Types
- Testing & Quality Assurance
- Prerequisites
- Setup
- Installation
- Configuration
- Usage Examples
- Authentication
- Error Handling
- Security Considerations
- Troubleshooting
- API Reference
- Solution Management Best Practices
- Developer Notebook
- Contributing
- Releasing
- Changelog
- License
- Support
Features
This MCP server provides comprehensive tools for Dataverse schema management:
Table Operations
- create_dataverse_table ✅ Fully Tested - Create Dataverse Table: Creates a new custom table in Dataverse with the specified configuration. Use this when you need to create a new entity to store business data. Requires a solution context to be set first.
- get_dataverse_table ✅ Fully Tested - Get Dataverse Table: Retrieves detailed information about a specific Dataverse table including its metadata, properties, and configuration. Use this to inspect table definitions and understand table structure.
- update_dataverse_table ✅ Fully Tested - Update Dataverse Table: Updates the properties and configuration of an existing Dataverse table. Use this to modify table settings like display names, descriptions, or feature enablement (activities, notes, auditing, etc.). Changes are published automatically.
- delete_dataverse_table ✅ Fully Tested - Delete Dataverse Table: Permanently deletes a custom table from Dataverse. WARNING: This action cannot be undone and will remove all data in the table. Use with extreme caution and only for tables that are no longer needed.
- list_dataverse_tables ✅ Fully Tested - List Dataverse Tables: Retrieves a list of tables in the Dataverse environment with filtering options. Use this to discover available tables, find custom tables, or get an overview of the data model. Supports filtering by custom/system tables and managed/unmanaged status.
Column Operations
- create_dataverse_column ✅ Fully Tested - Create Dataverse Column: Creates a new column (field) in a Dataverse table with the specified data type and configuration. Supports various column types including text, numbers, dates, lookups, and choice lists. Use this to add new fields to store specific data in your tables. Requires a solution context to be set first.
- get_dataverse_column ✅ Fully Tested - Get Dataverse Column: Retrieves detailed information about a specific column in a Dataverse table, including its data type, properties, and configuration settings. Use this to inspect column definitions and understand field structure.
- update_dataverse_column ✅ Fully Tested - Update Dataverse Column: Updates the properties and configuration of an existing column in a Dataverse table. Use this to modify column settings like display names, descriptions, required levels, or audit settings. Note that data type cannot be changed after creation.
- delete_dataverse_column ✅ Fully Tested - Delete Dataverse Column: Permanently deletes a column from a Dataverse table. WARNING: This action cannot be undone and will remove all data stored in this column. Use with extreme caution and only for columns that are no longer needed.
- list_dataverse_columns ✅ Fully Tested - List Dataverse Columns: Retrieves a list of columns in a specific Dataverse table with filtering options. Use this to discover available fields in a table, find custom columns, or get an overview of the table structure. Supports filtering by custom/system columns and managed/unmanaged status.
Relationship Operations
- create_dataverse_relationship ✅ Fully Tested - Create Dataverse Relationship: Creates a relationship between two Dataverse tables. Supports One-to-Many relationships (parent-child with lookup field) and Many-to-Many relationships (junction table). Use this to establish data connections between tables, enable navigation, and maintain referential integrity.
- get_dataverse_relationship ✅ Fully Tested - Get Dataverse Relationship: Retrieves detailed information about a specific relationship between Dataverse tables, including its configuration, cascade settings, and menu behavior. Use this to inspect relationship definitions and understand table connections.
- delete_dataverse_relationship ✅ Fully Tested - Delete Dataverse Relationship: Permanently deletes a relationship between Dataverse tables. WARNING: This action cannot be undone and will remove the connection between tables, including any lookup fields for One-to-Many relationships. Use with extreme caution.
- list_dataverse_relationships ✅ Fully Tested - List Dataverse Relationships: Retrieves a list of relationships in the Dataverse environment with filtering options. Use this to discover table connections, find custom relationships, or get an overview of the data model relationships. Supports filtering by entity, relationship type, and managed/unmanaged status.
Option Set Operations
- create_dataverse_optionset ✅ Fully Tested - Create Dataverse Option Set: Creates a new global option set (choice list) in Dataverse with predefined options. Use this to create reusable choice lists that can be used across multiple tables and columns. Option sets provide consistent data entry options and improve data quality.
- get_dataverse_optionset ✅ Fully Tested - Get Dataverse Option Set: Retrieves detailed information about a specific option set including its metadata, options, and configuration. Use this to inspect option set definitions and understand available choices.
- update_dataverse_optionset ✅ Fully Tested - Update Dataverse Option Set: Updates an existing option set by modifying its properties and managing its options. Use this to add new choices, update existing ones, remove obsolete options, or change the option set's display name and description. Changes affect all columns using this option set.
- delete_dataverse_optionset ✅ Fully Tested - Delete Dataverse Option Set: Permanently deletes an option set from Dataverse. WARNING: This action cannot be undone and will fail if the option set is being used by any columns. Ensure no columns reference this option set before deletion.
- list_dataverse_optionsets ✅ Fully Tested - List Dataverse Option Sets: Retrieves a list of option sets in the Dataverse environment with filtering options. Use this to discover available choice lists, find custom option sets, or get an overview of reusable options. Supports filtering by custom/system and managed/unmanaged status.
- get_dataverse_optionset_options ✅ Fully Tested - Get Dataverse Option Set Options: Retrieves all options (choices) within a specific option set, including their values, labels, descriptions, and colors. Use this to inspect the available choices in an option set and understand their configuration.
Solution & Publisher Operations
- create_dataverse_publisher ✅ Fully Tested - Create Dataverse Publisher: Creates a new publisher in Dataverse. Publishers are required for creating solutions and provide customization prefixes for schema names. Use this to establish a publisher identity before creating solutions and custom components.
- get_dataverse_publisher ✅ Fully Tested - Get Dataverse Publisher: Retrieves detailed information about a specific publisher including its customization prefix, option value prefix, and configuration. Use this to inspect publisher properties and understand customization settings.
- list_dataverse_publishers ✅ Fully Tested - List Dataverse Publishers: Retrieves a list of publishers in the Dataverse environment with filtering options. Use this to discover available publishers, find custom publishers for solution creation, or get an overview of publisher configurations including customization prefixes.
- create_dataverse_solution ✅ Fully Tested - Create Dataverse Solution: Creates a new unmanaged solution in Dataverse. Solutions are containers for customizations and allow you to package, deploy, and manage custom components. Use this to create a solution before adding tables, columns, and other customizations.
- get_dataverse_solution ✅ Fully Tested - Get Dataverse Solution: Retrieves detailed information about a specific solution including its metadata, version, publisher details, and configuration. Use this to inspect solution properties and understand solution structure.
- list_dataverse_solutions ✅ Fully Tested - List Dataverse Solutions: Retrieves a list of solutions in the Dataverse environment with filtering options. Use this to discover available solutions, find unmanaged solutions for customization, or get an overview of solution packages. Includes publisher information for each solution.
- set_solution_context ✅ Fully Tested - Set Solution Context: Sets the active solution context for all subsequent metadata operations. When a solution context is set, all created tables, columns, relationships, and other components will be automatically added to this solution. This is required before creating any custom components.
- get_solution_context ✅ Fully Tested - Get Solution Context: Retrieves the currently active solution context information. Use this to check which solution is currently set for metadata operations and to verify the customization prefix being used for new components.
- clear_solution_context ✅ Fully Tested - Clear Solution Context: Clears the currently active solution context. After clearing, metadata operations will not be associated with any specific solution. Use this when you want to work without a solution context or before switching to a different solution.
Security Role Operations
- create_dataverse_role ✅ Fully Tested - Create Dataverse Security Role: Creates a new security role in Dataverse to define permissions and access levels for users and teams. Security roles control what users can see and do within the system. Use this to establish custom permission sets for different user types or job functions.
- get_dataverse_role ✅ Fully Tested - Get Dataverse Security Role: Retrieves detailed information about a specific security role including its properties, business unit association, and configuration settings. Use this to inspect role definitions and understand permission structures.
- update_dataverse_role ✅ Fully Tested - Update Dataverse Security Role: Updates the properties and configuration of an existing security role. Use this to modify role settings like name, description, auto-assignment behavior, or inheritance settings without changing the actual privileges.
- delete_dataverse_role ✅ Fully Tested - Delete Dataverse Security Role: Permanently deletes a security role from Dataverse. WARNING: This action cannot be undone and will fail if the role is assigned to any users or teams. Ensure the role is not in use before deletion.
- list_dataverse_roles ✅ Fully Tested - List Dataverse Security Roles: Retrieves a list of security roles in the Dataverse environment with filtering options. Use this to discover available roles, find custom roles, or get an overview of permission structures. Supports filtering by business unit, custom/system roles, and managed/unmanaged status.
- add_privileges_to_role ✅ Fully Tested - Add Privileges to Security Role: Adds specific privileges with defined access levels to a security role. Use this to grant permissions for specific operations (create, read, write, delete, etc.) on entities or system functions. Each privilege can have different access levels (Basic, Local, Deep, Global).
- remove_privilege_from_role ✅ Fully Tested - Remove Privilege from Security Role: Removes a specific privilege from a security role, revoking the associated permissions. Use this to restrict access by removing specific operation permissions from a role.
- replace_role_privileges ✅ Fully Tested - Replace Security Role Privileges: Completely replaces all existing privileges in a security role with a new set of privileges. WARNING: This removes all current privileges and replaces them with the specified ones. Use this for comprehensive role permission restructuring.
- get_role_privileges ✅ Fully Tested - Get Security Role Privileges: Retrieves all privileges currently assigned to a security role, showing what permissions the role grants. Use this to audit role permissions and understand what access a role provides to users and teams.
- assign_role_to_user ✅ Fully Tested - Assign Security Role to User: Assigns a security role to a specific user, granting them all the permissions defined in that role. Use this to provide users with the appropriate access levels for their job functions and responsibilities.
- remove_role_from_user ✅ Fully Tested - Remove Security Role from User: Removes a security role assignment from a specific user, revoking the permissions granted by that role. Use this when users change roles or no longer need certain access levels.
- assign_role_to_team ✅ Fully Tested - Assign Security Role to Team: Assigns a security role to a team, granting all team members the permissions defined in that role. Use this to provide consistent access levels to groups of users working together on similar tasks.
- remove_role_from_team ✅ Fully Tested - Remove Security Role from Team: Removes a security role assignment from a team, revoking the permissions granted by that role for all team members. Use this when teams no longer need certain access levels or when restructuring team permissions.
Team Operations
- create_dataverse_team ✅ Fully Tested - Create Dataverse Team: Creates a new team in Dataverse for organizing users and managing permissions. Teams can be owner teams (for record ownership) or access teams (for sharing records). Use this to establish groups of users who work together and need similar access levels.
- get_dataverse_team ✅ Fully Tested - Get Dataverse Team: Retrieves detailed information about a specific team including its properties, administrator, business unit association, and configuration settings. Use this to inspect team definitions and understand team structure.
- update_dataverse_team ✅ Fully Tested - Update Dataverse Team: Updates the properties and configuration of an existing team. Use this to modify team settings like name, description, administrator, or other team properties without changing team membership.
- delete_dataverse_team ✅ Fully Tested - Delete Dataverse Team: Permanently deletes a team from Dataverse. WARNING: This action cannot be undone and will fail if the team owns records or has assigned security roles. Ensure the team is not in use before deletion.
- list_dataverse_teams ✅ Fully Tested - List Dataverse Teams: Retrieves a list of teams in the Dataverse environment with filtering options. Use this to discover available teams, find teams by business unit or type, or get an overview of team organization. Supports filtering by business unit, team type, and system-managed status.
- add_members_to_team ✅ Fully Tested - Add Members to Team: Adds users as members to a team, granting them access to team-owned records and team-based permissions. Use this to expand team membership and provide users with team-level access to resources.
- remove_members_from_team ✅ Fully Tested - Remove Members from Team: Removes users from team membership, revoking their access to team-owned records and team-based permissions. Use this when users no longer need team access or are changing roles.
- get_team_members ✅ Fully Tested - Get Team Members: Retrieves a list of all users who are members of a specific team, including their basic information and status. Use this to audit team membership and understand who has team-based access.
- convert_owner_team_to_access_team ✅ Fully Tested - Convert Owner Team to Access Team: Converts an owner team to an access team, changing how the team can be used for record ownership and sharing. WARNING: This action cannot be undone and affects how records owned by this team are managed.
Business Unit Operations
- create_dataverse_businessunit ✅ Fully Tested - Create Dataverse Business Unit: Creates a new business unit in Dataverse with comprehensive configuration options including contact information, addresses, and organizational hierarchy. Business units are used to organize users and control data access in Dataverse.
- get_dataverse_businessunit ✅ Fully Tested - Get Dataverse Business Unit: Retrieves detailed information about a specific business unit including all properties, addresses, and related information. Use this to inspect business unit configuration and hierarchy relationships.
- update_dataverse_businessunit ✅ Fully Tested - Update Dataverse Business Unit: Updates the properties and configuration of an existing business unit. Use this to modify business unit information, contact details, addresses, and organizational settings. Only provided fields will be updated.
- delete_dataverse_businessunit ✅ Fully Tested - Delete Dataverse Business Unit: Permanently deletes a business unit from Dataverse. WARNING: This action cannot be undone and may affect users and teams associated with the business unit. Use with extreme caution.
- list_dataverse_businessunits ✅ Fully Tested - List Dataverse Business Units: Retrieves a list of business units in the Dataverse environment with filtering and sorting options. Use this to discover available business units, understand organizational hierarchy, and find specific business units by criteria.
- get_businessunit_hierarchy ✅ Fully Tested - Get Business Unit Hierarchy: Retrieves the complete organizational hierarchy for a specific business unit, showing parent-child relationships and the full organizational structure. Use this to understand business unit relationships and organizational structure.
- set_businessunit_parent ✅ Fully Tested - Set Business Unit Parent: Changes the parent business unit for a given business unit, effectively moving it within the organizational hierarchy. Use this to reorganize business unit structure and reporting relationships.
- get_businessunit_users ✅ Fully Tested - Get Business Unit Users: Retrieves all users associated with a specific business unit, with option to include users from subsidiary business units. Use this to understand user assignments and organizational membership.
- get_businessunit_teams ✅ Fully Tested - Get Business Unit Teams: Retrieves all teams associated with a specific business unit, with option to include teams from subsidiary business units. Use this to understand team organization and business unit relationships.
Schema Export Operations
- export_solution_schema ✅ Fully Tested - Export Solution Schema: Exports a comprehensive JSON schema of Dataverse tables, columns, relationships, and option sets. Use this to document your data model, generate diagrams, or analyze solution structure. Supports filtering by prefixes, system/custom components, and specific tables.
- generate_mermaid_diagram ✅ Fully Tested - Generate Mermaid Diagram: Generates a Mermaid entity relationship diagram from an exported schema JSON file. Creates visual documentation of your data model with tables, columns, and relationships. Perfect for documentation, presentations, and understanding data structure.
WebAPI Call Generator
- generate_webapi_call ✅ Fully Tested - Generate Dataverse WebAPI Call: Generate HTTP requests, curl commands, and JavaScript examples for Dataverse WebAPI operations. Supports all CRUD operations, associations, actions, and functions with proper OData query parameters and headers.
PowerPages WebAPI Generator
- generate_powerpages_webapi_call ✅ Fully Tested - Generate PowerPages WebAPI Call: Generate PowerPages-specific API calls, JavaScript examples, and React components for Dataverse operations through PowerPages portals. Includes authentication context and portal-specific patterns.
PowerPages Configuration Management
- manage_powerpages_webapi_config ✅ Fully Tested - Manage PowerPages WebAPI Configuration: Manage PowerPages WebAPI configurations and table permissions. Add/remove WebAPI access for tables, configure table permissions, and check configuration status for PowerPages portals.
Solution-Based Architecture
The MCP server implements enterprise-grade solution management following Microsoft Dataverse best practices.
Key Benefits
- Professional Schema Naming: Uses publisher-based customization prefixes
- Solution Association: All schema changes are automatically associated with the active solution
- ALM Support: Enables proper solution packaging and deployment across environments
- Persistent Context: Solution context survives server restarts via
.mcp-dataverse
file - Enterprise Governance: Supports multiple publishers and solutions with proper isolation
Solution Workflow
- Create Publisher: Define your organization's customization prefix
- Create Solution: Link solution to publisher for schema organization
- Set Context: Activate solution for subsequent operations
- Create Schema: All tables, columns, and option sets use the publisher's prefix automatically
- Deploy: Export solution for deployment to other environments
Example: XYZ Organization Setup
Persistent Solution Context
The server automatically persists solution context to a .mcp-dataverse
file in the project root:
Benefits of Persistence:
- No Context Loss: Solution context survives server restarts
- Instant Productivity: Developers can immediately continue work
- Consistent Prefixes: No need to remember and re-set solution context
- Team Isolation: Each developer can have their own solution context (file is git-ignored)
Supported Column Types
The MCP server supports all major Dataverse column types with comprehensive configuration options. The following table shows implementation status and comprehensive testing verification:
Column Type | Status | Tested | Description | Key Parameters |
---|---|---|---|---|
String | ✅ Implemented | ✅ Fully Verified | Text fields with format options | maxLength , format (Email, Text, TextArea, Url, Phone) |
Integer | ✅ Implemented | ✅ Fully Verified | Whole numbers with constraints | minValue , maxValue (defaultValue not supported) |
Decimal | ✅ Implemented | ✅ Fully Verified | Decimal numbers with precision | precision , minValue , maxValue , defaultValue |
Money | ✅ Implemented | ✅ Fully Verified | Currency values | precision , minValue , maxValue |
Boolean | ✅ Implemented | ✅ Fully Verified | True/false with custom labels | trueOptionLabel , falseOptionLabel , defaultValue |
DateTime | ✅ Implemented | ✅ Fully Verified | Date and time fields | dateTimeFormat (DateOnly, DateAndTime) |
Picklist | ✅ Implemented | ✅ Fully Verified | Choice fields (local & global) | options (for local), optionSetName (for global) |
Lookup | ✅ Implemented | ✅ Fully Verified | References to other tables | targetEntity |
Memo | ✅ Implemented | ✅ Fully Verified | Long text fields | maxLength |
Double | ✅ Implemented | ✅ Fully Verified | Floating-point numbers | precision , minValue , maxValue |
BigInt | ✅ Implemented | ✅ Fully Verified | Large integer values | None |
Column Type Details
String Columns ✅ Fully Tested
- Formats: Email, Text, TextArea, Url, Phone
- Max Length: Configurable (default: 100)
- Default Values: Supported
- Example: Employee name, email address, phone number
Integer Columns ✅ Fully Tested
- Constraints: Min/max value validation
- Default Values: Not supported (Dataverse limitation)
- Example: Age, quantity, score with range 0-100
Boolean Columns ✅ Fully Tested
- Custom Labels: Configurable true/false option labels
- Default Values: Supported
- Example: "Active/Inactive", "Yes/No", "Enabled/Disabled"
DateTime Columns ✅ Fully Tested
- DateOnly: Date without time component (e.g., hire date, birthday)
- DateAndTime: Full timestamp with timezone handling (e.g., last login, created date)
- Behavior: Uses UserLocal timezone behavior
Picklist Columns ✅ Fully Tested
- Local Option Sets: Create inline options with the column
- Global Option Sets: Reference existing global option sets by name
- Color Support: Options can have associated colors
- Example: Status (Active, Inactive), Priority (High, Medium, Low)
Lookup Columns ✅ Fully Tested
- Target Entity: Specify which table to reference
- Relationships: Automatically creates underlying relationship
- Example: Customer lookup, Account reference
Tested Column Scenarios
The following specific scenarios have been successfully tested and verified in comprehensive testing:
- String Column Creation ✅ Verified
- Basic text field with default settings
- Email format validation
- Custom max length constraints
- Integer Column Creation ✅ Verified
- Numeric field with min/max constraints (0-100 range)
- Default value handling (not supported - properly handled)
- Boolean Column Creation ✅ Verified
- Custom true/false labels ("Active"/"Inactive")
- Default value configuration
- DateTime Column Creation ✅ Verified
- DateOnly format for hire dates
- DateAndTime format for login timestamps
- Picklist Column Creation ✅ Verified
- Local option set with custom options
- Global option set reference using existing option sets
- Lookup Column Creation ✅ Verified
- Cross-table reference creation
- Automatic relationship creation
- Decimal Column Creation ✅ Verified
- Precision and scale configuration
- Min/max value constraints
- Money Column Creation ✅ Verified
- Currency field with precision
- Proper money data type handling
- Memo Column Creation ✅ Verified
- Long text field configuration
- Max length settings
- Double Column Creation ✅ Verified
- Floating-point number handling
- Precision configuration
- BigInt Column Creation ✅ Verified
- Large integer value support
- Proper data type handling
Column Operations Status
Operation | Status | Description |
---|---|---|
Create | ✅ Fully Tested | All column types with type-specific parameters |
Read | ✅ Fully Tested | Retrieve column metadata and configuration |
Update | ✅ Fully Tested | Modify display name, description, required level |
Delete | ✅ Fully Tested | Remove custom columns from tables (with dependency checking) |
List | ✅ Fully Tested | List all columns for a table with filtering |
Testing & Quality Assurance
This MCP server has undergone comprehensive testing to ensure production readiness:
Test Coverage
- ✅ 22 Major Test Phases Completed
- ✅ 100% Tool Coverage - All 40+ tools tested
- ✅ All Column Types Verified - Complete testing of all 11 supported column types
- ✅ All Relationship Types Tested - One-to-Many and Many-to-Many relationships
- ✅ Complete CRUD Operations - Create, Read, Update, Delete for all entity types
- ✅ Error Handling Validated - Edge cases and invalid input handling
- ✅ Microsoft Dataverse API Compliance - Full compliance with official API standards
Bugs Found and Fixed
During comprehensive testing, 7 critical bugs were identified and resolved:
- Integer Column Default Value Bug - Fixed unsupported DefaultValue property for IntegerAttributeMetadata
- Table Update Method Bug - Fixed to use PUT instead of PATCH for EntityMetadata updates
- Column Update Method Bug - Fixed to use PUT instead of PATCH for AttributeMetadata updates
- PublishXml Action Prefix Bug - Fixed global action calling without Microsoft.Dynamics.CRM prefix
- Option Set Update Method Bug - Fixed to use MetadataId instead of Name for PUT operations
- UpdateOptionValue Missing Parameter Bug - Added required MergeLabels parameter
- Option Set Action Prefix Bug - Fixed option set actions to not include incorrect prefix
Test Documentation
- Pet Store Example - Complete testing documentation with pet store schema example
- COMPREHENSIVE_TEST_PLAN.md - Complete 284-line systematic test plan
- COMPREHENSIVE_TEST_REPORT.md - Detailed test results and bug fixes
Production Readiness
- ✅ Robust Error Handling - Comprehensive error handling for all scenarios
- ✅ Dependency Management - Proper handling of entity dependencies and constraints
- ✅ Security Compliance - Full security role and permission management
- ✅ Performance Validated - Tested with large schemas and bulk operations
- ✅ Microsoft Standards Compliant - Follows all Microsoft Dataverse best practices
Prerequisites
- Dataverse Environment - You need access to a Microsoft Dataverse environment
- Azure App Registration - An Azure AD app registration with appropriate permissions
- Client Credentials - Client ID, Client Secret, and Tenant ID for authentication
Setup
1. Azure App Registration
- Go to the Azure Portal
- Navigate to Azure Active Directory > App registrations
- Click New registration
- Provide a name (e.g., "Dataverse MCP Server")
- Select Accounts in this organizational directory only
- Click Register
2. Create Client Secret
- Go to Certificates & secrets
- Click New client secret
- Provide a description and expiration
- Click Add
- Copy the secret value immediately (you won't be able to see it again)
3. Create Application User in Dataverse
Critical Step: You must create an Application User in your Dataverse environment and assign appropriate permissions.
- Navigate to Dataverse Admin Center
- Go to Power Platform Admin Center
- Select your environment
- Go to Settings > Users + permissions > Application users
- Create Application User
- Click + New app user
- Click + Add an app
- Search for and select your Azure app registration (by Client ID)
- Enter a Business unit (usually the root business unit)
- Click Create
- Assign Security Roles
- Select the newly created application user
- Click Manage roles
- Assign appropriate security roles based on your needs:
- System Administrator: Full access (recommended for development/testing)
- System Customizer: Schema operations without data access
- Custom Role: Create specific permissions for production use
- Verify Application User Status
- Ensure the application user is Enabled
- Verify it shows as Application type (not User)
- Note the Application ID matches your Azure app registration Client ID
4. Get Required Information
You'll need:
- Tenant ID: Found in Azure AD > Overview
- Client ID: Found in your app registration > Overview
- Client Secret: The secret you just created
- Dataverse URL: Your Dataverse environment URL (e.g.,
https://yourorg.crm.dynamics.com
)
Installation
- Install dependencies:
- Build the server:
- Copy the full path to the built
index.js
file:- The server will be built to the
build/
directory - Copy the complete file path (e.g.,
/Users/yourname/path/to/mcp-dataverse/build/index.js
) - You'll use this path in your MCP configuration file
- The server will be built to the
- Configure the MCP server in your MCP settings file using the copied path (see Configuration section below for details)
Configuration
The server supports flexible environment variable configuration with the following precedence (highest to lowest):
- MCP environment variables (highest priority)
- System environment variables
.env
file variables (lowest priority)
Windows MCP Configuration
For Windows users, the MCP configuration requires using cmd
with the /c
flag to properly execute the Node.js server:
Important Windows Notes:
- Use
cmd
as the command with/c
flag - Use full Windows paths with double backslashes (
\\
) or forward slashes (/
) - The
timeout
setting is increased to 900 seconds (15 minutes) for longer operations - Environment variables can be configured directly in the MCP settings as shown above
⚠️ Security Warning: If you store your MCP settings file in your project directory (rather than in a global MCP configuration location), make sure to add it to your .gitignore
file to prevent accidentally committing sensitive credentials:
Option 1: Using .env file (Recommended for MCP Server Development)
The server automatically loads environment variables from a .env
file in the project root. This is the recommended approach when contributing to or modifying the MCP server itself.
- Create your
.env
file:
- Add the following configuration to your MCP settings file:
Note: The timeout
setting is increased to 900 seconds (15 minutes) to accommodate longer-running operations like schema export, which may need to process large amounts of metadata.
Option 2: Using MCP environment variables (Recommended for Normal Usage)
You can configure environment variables directly in the MCP settings. This is the recommended approach for normal usage when using the MCP Dataverse tool for development activities. These will override any values in the .env
file:
⚠️ Security Warning: If you store your MCP settings file in your project directory (rather than in a global MCP configuration location), make sure to add it to your .gitignore
file to prevent accidentally committing sensitive credentials:
Option 3: Hybrid Configuration
You can also use a combination approach where common settings are in .env
and sensitive or environment-specific settings are overridden via MCP:
.env file:
MCP settings (overrides for production):
Usage Examples
Creating a Custom Table
Important: Before creating tables, ensure you have set a solution context using set_solution_context
to provide the customization prefix. The system automatically uses the prefix from the active solution's publisher.
Adding Columns to a Table
Creating Relationships
Managing Option Sets
Managing Security Roles
Managing Teams
Managing Business Units
Exporting Solution Schema
Schema Export Features:
- Schema Capture: Exports tables, columns, and global option sets (relationships not yet implemented)
- Flexible Filtering: Choose to include or exclude system entities
- Solution Context Aware: Automatically includes solution metadata when context is set
- Comprehensive Metadata: Captures all entity properties and column types
- JSON Format: Human-readable or minified output options
- Directory Creation: Automatically creates output directories if they don't exist
Example Output Structure:
Enhanced Features:
- Multiple Customization Prefixes: Export tables from multiple publishers simultaneously
- Column Prefix Exclusion: Filter out unwanted columns (default excludes: adx_, msa_, msdyn_, mspp_)
- Primary Key Inclusion: All Primary Key columns are automatically included regardless of system column settings
- Improved System Table Filtering: Better control over which system tables to include with sensible defaults
Mermaid Diagram Generation
The Mermaid Diagram Generation tool converts exported JSON schemas into professional Entity Relationship Diagrams using Mermaid syntax. This provides visual documentation of your Dataverse schema with relationships, column details, and professional formatting.
Key Features
- Professional ERD Generation: Creates publication-ready Entity Relationship Diagrams
- Schema-Based Relationships: Uses only exported relationship metadata for accurate representation
- Enhanced Column Markers: Visual indicators for Primary Keys (PK), Foreign Keys (FK), Primary Names (PN), and required fields
- Lookup Target Display: Shows which tables each lookup column references (e.g., "Lookup (contact, account)")
- Table Filtering: Filter diagrams to specific tables using
tableNameFilter
parameter - Comprehensive Headers: Generated files include complete context and regeneration instructions
- Mermaid Compatibility: Works with Mermaid Live Editor, VS Code extensions, GitHub, and documentation tools
Usage Examples
Example Output
The tool generates professional Mermaid ERD syntax like this:
Column Markers Explained
- PK: Primary Key columns (unique identifiers)
- FK: Foreign Key columns (lookup references)
- Primary Name: The display name column for records
- NOT NULL: Required fields
- Lookup (table1, table2): Shows which tables the lookup column can reference
Diagram Features
- Table Visualization: Each table shows its logical name and all columns
- Column Details: Data types, constraints, and special markers
- Relationship Lines: Visual connections between related tables
- Cardinality Indicators: Shows one-to-many (||--o{) and many-to-many (}o--o{) relationships
- Professional Formatting: Clean, readable diagrams suitable for documentation
Integration with Documentation Tools
Generated Mermaid diagrams work seamlessly with:
- Mermaid Live Editor (https://mermaid.live) - Online diagram editor and viewer
- VS Code Mermaid Preview - Real-time diagram preview in your editor
- GitHub/GitLab - Native Mermaid support in markdown files
- Documentation Sites - Gitiles, MkDocs, and other documentation platforms
- Confluence - Via Mermaid plugins for enterprise documentation
Workflow Example
- Export Schema: Use
export_solution_schema
to create JSON schema file - Generate Diagram: Use
generate_mermaid_diagram
to create visual ERD - Review Relationships: Verify all lookup columns show correct target tables
- Documentation: Include diagrams in project documentation or wiki
- Team Sharing: Share visual schema with stakeholders and developers
This tool is essential for documenting complex Dataverse schemas and communicating data relationships to both technical and non-technical stakeholders.
WebAPI Call Generator
The WebAPI Call Generator tool helps developers construct proper Dataverse WebAPI calls by generating complete HTTP requests with correct URLs, headers, and request bodies. This is particularly useful for:
- Learning WebAPI syntax - See how different operations translate to HTTP calls
- Debugging API issues - Generate reference calls to compare against your implementation
- Documentation - Create examples for team members or API documentation
- Testing - Get ready-to-use cURL commands and JavaScript fetch examples
Output Features:
- Complete HTTP Request: Method, URL, headers, and body
- cURL Command: Ready-to-execute command-line example
- JavaScript Fetch: Copy-paste JavaScript code
- Solution Context: Automatically includes current solution headers
- Authentication Placeholder: Optional Bearer token placeholder
- OData Query Building: Proper encoding of complex filter expressions
Example Output:
Supported Operations:
- retrieve - Get a single record by ID
- retrieveMultiple - Query multiple records with OData
- create - Create new records
- update - Update existing records (PATCH)
- delete - Delete records
- associate - Create relationships between records
- disassociate - Remove relationships between records
- callAction - Execute Dataverse actions (bound/unbound)
- callFunction - Execute Dataverse functions (bound/unbound)
Advanced Features:
- OData Query Options: $select, $filter, $orderby, $top, $skip, $expand, $count
- Prefer Headers: return=representation, odata.include-annotations=*
- Conditional Updates: If-Match, If-None-Match headers
- Impersonation: MSCRMCallerID header support
- Solution Context: Automatic MSCRM.SolutionUniqueName header inclusion
PowerPages WebAPI Generator
The PowerPages WebAPI Generator creates API calls specifically for PowerPages Single Page Applications (SPAs) using the PowerPages WebAPI format /_api/[logicalEntityName]s
. This tool is designed for developers building modern React, Angular, or Vue applications within PowerPages environments.
Key Differences from Standard Dataverse WebAPI:
- URL Format: Uses
/_api/[logicalEntityName]s
instead of/api/data/v9.2/[entitySetName]
(note: 's' suffix is automatically added) - Authentication: Integrates with PowerPages authentication context and request verification tokens
- Client-Side Focus: Optimized for browser-based applications with React component examples
- PowerPages Security: Respects PowerPages table permissions and web roles
Output Features:
- PowerPages URL Format: Correct
/_api/[logicalEntityName]s
endpoint construction (automatic 's' suffix) - Request Verification Token: Automatic token handling for POST/PATCH/DELETE operations
- JavaScript Examples: Ready-to-use fetch code with error handling
- React Components: Complete React hook examples for data fetching
- Authentication Context: PowerPages user context and token management
- OData Query Support: Full OData query parameter support with proper encoding
Example Output:
React Component Example:
Authentication Context Integration:
PowerPages-Specific Features:
- Request Verification Token: Automatic
__RequestVerificationToken
header handling for secure operations - Authentication Integration: Built-in PowerPages user context access
- React-Ready: Complete React component examples with hooks and state management
- Error Handling: Comprehensive error handling patterns for PowerPages environments
- Security Compliance: Respects PowerPages table permissions and web role security
- SPA Optimization: Designed for single-page application development patterns
Supported Operations:
- retrieve - Get a single record by ID
- retrieveMultiple - Query multiple records with OData filtering
- create - Create new records with request verification token
- update - Update existing records (PATCH) with token handling
- delete - Delete records with proper authentication
This tool is essential for PowerPages developers building modern SPAs that need to interact with Dataverse data while maintaining PowerPages security and authentication patterns.
PowerPages Configuration Management
The manage_powerpages_webapi_config
tool helps manage table permissions and WebAPI site settings for PowerPages Code Sites. It automates the configuration of YAML files in the .powerpages-site
directory structure, making it easier to set up and maintain WebAPI access for your PowerPages applications.
Key Features
- Automated YAML Management: Creates and updates sitesetting.yml, webrole.yml, and table permission files
- WebAPI Configuration: Enables WebAPI access with proper site settings
- Table Permissions: Manages granular permissions for specific tables and web roles
- Status Checking: Provides comprehensive status of current configurations
- PowerPages Code Site Integration: Works seamlessly with the
.powerpages-site
directory structure
Usage Examples
Check Configuration Status
Sample Output:
Enable WebAPI for a Table
Result:
- Updates
.powerpages-site/sitesetting.yml
with WebAPI settings - Enables WebAPI access for the specified table
- Configures allowed fields for WebAPI operations
Create Table Permissions
Result:
- Creates
.powerpages-site/table-permissions/cr7ae_creditcardses_authenticated_users.yml
- Configures specific CRUD permissions for the web role
- Sets appropriate scope (Global, Contact, Account, Self, Parent, etc.)
List Current Configurations
Sample Output:
Operations
status
Provides a comprehensive overview of the current PowerPages WebAPI configuration including:
- WebAPI enablement status for tables
- Configured fields and permissions
- Web role definitions
- Table permission summaries
configure-webapi
Enables or configures WebAPI access for specific tables:
- tableName (required): Logical name of the table
- fields (optional): Array of field names to allow in WebAPI calls
- enabled (optional): Boolean to enable/disable WebAPI access
create-table-permission
Creates granular table permissions for web roles:
- tableName (required): Logical name of the table
- webRoleName (required): Name of the web role
- permissions (required): Object with read, create, write, delete boolean values
- scope (optional): Permission scope (Global, Contact, Account, Self, Parent, etc.)
list-configurations
Lists all current configurations including:
- Site settings with their values
- Web roles with IDs
- Table permissions with detailed permission breakdown
PowerPages Code Site Integration
This tool is designed to work with PowerPages Code Sites that follow the standard directory structure:
Example Workflow
- Check Current Status:
- Enable WebAPI for Your Custom Table:
- Create Table Permissions:
- Verify Configuration:
- Use with PowerPages WebAPI Generator:
This workflow ensures your PowerPages Code Site is properly configured to handle WebAPI calls for your custom tables with appropriate security permissions.
Authentication
The server uses Client Credentials flow (Server-to-Server authentication) with Azure AD. This provides:
- Secure authentication without user interaction
- Application-level permissions
- Suitable for automated scenarios
- Token refresh handling
Error Handling
The server includes comprehensive error handling:
- Authentication errors - Invalid credentials or expired tokens
- API errors - Dataverse-specific error messages with codes
- Validation errors - Parameter validation and type checking
- Network errors - Connection and timeout handling
Security Considerations
- Store secrets securely - Never commit client secrets to version control
- Use environment variables - Configure secrets through environment variables
- Principle of least privilege - Grant only necessary permissions
- Monitor usage - Track API calls and authentication attempts
- Rotate secrets regularly - Update client secrets periodically
Troubleshooting
Common Issues
- Authentication Failed
- Verify client ID, secret, and tenant ID
- Check that the app registration is properly configured
- Permission Denied
- Verify Application User Exists: Check that an application user has been created in Dataverse for your app registration
- Check Security Roles: Ensure the application user has appropriate security roles:
- System Administrator: Required for full schema operations
- System Customizer: Minimum for table/column operations
- Environment Maker: May be needed for solution operations
- Verify User Status: Ensure the application user is enabled and not disabled
- Check Business Unit: Verify the application user is assigned to the correct business unit
- Validate Client ID: Confirm the Application ID in Dataverse matches your Azure app registration Client ID
- Entity Not Found
- Verify entity logical names are correct
- Check if entities exist in the target environment
- Invalid Column Type
- Review supported column types in the documentation
- Verify required parameters for specific column types
Debug Mode
Set environment variable DEBUG=true
for verbose logging:
API Reference
For detailed parameter information for each tool, refer to the tool definitions in the source code:
src/tools/table-tools.ts
- Table operationssrc/tools/column-tools.ts
- Column operationssrc/tools/relationship-tools.ts
- Relationship operationssrc/tools/optionset-tools.ts
- Option set operationssrc/tools/solution-tools.ts
- Solution and publisher operationssrc/tools/role-tools.ts
- Security role operationssrc/tools/team-tools.ts
- Team operationssrc/tools/businessunit-tools.ts
- Business unit operationssrc/tools/schema-tools.ts
- Schema export operationssrc/tools/webapi-tools.ts
- WebAPI call generator operationssrc/tools/powerpages-webapi-tools.ts
- PowerPages WebAPI call generator operationssrc/tools/powerpages-config-tools.ts
- PowerPages configuration management operations
Solution Management Best Practices
Publisher Configuration
When creating publishers, follow these guidelines:
- Unique Prefixes: Use 2-8 character prefixes that identify your organization
- Option Value Ranges: Use non-overlapping ranges (e.g., 10000-19999 for one publisher, 20000-29999 for another)
- Descriptive Names: Use clear, professional names for publishers and solutions
Solution Context Management
Environment Promotion
- Development: Create and test schema changes in dev environment with solution context
- Export: Use Power Platform CLI or admin center to export solution
- Import: Deploy solution to test/production environments
- Validation: Verify all customizations use proper prefixes
Git Integration
The .mcp-dataverse
file is automatically excluded from version control:
This allows each developer to maintain their own solution context while preventing accidental sharing of environment-specific settings.
Developer Notebook
MCP Configuration Recommendations
This section provides real-world recommendations for configuring the Dataverse MCP server to accelerate development workflows.
Read-Only Tools for alwaysAllow
Configuration
For faster development cycles, consider adding these read-only tools to your MCP server's alwaysAllow
configuration. Since these tools only read data and don't make any changes to your Dataverse environment, they're safe to auto-approve and won't cause any side effects.
Recommended alwaysAllow
configuration:
Benefits of This Configuration
🚀 Accelerated Development:
- No approval prompts for schema exploration
- Instant access to table and column information
- Quick solution and publisher lookups
- Immediate schema documentation generation
🔒 Zero Risk:
- All listed tools are read-only operations
- No data modification or schema changes
- Safe for production environment connections
- No side effects or unintended consequences
📊 Enhanced Productivity:
- Faster debugging and troubleshooting
- Instant schema validation and exploration
- Quick relationship and dependency analysis
- Seamless documentation generation workflow
Common Development Workflows
Schema Exploration:
Solution Analysis:
Documentation Generation:
WebAPI Code Generation:
Developer Security Considerations
While these tools are read-only and safe, consider these security practices:
- Environment Separation: Use different MCP configurations for dev/test/prod environments
- Credential Management: Store sensitive credentials in secure environment variables
- Access Monitoring: Regularly review which tools are in
alwaysAllow
lists - Team Guidelines: Establish team standards for MCP configuration management
Advanced Configuration Tips
Selective Tool Enabling: If you prefer more granular control, start with the most commonly used read-only tools:
This configuration approach significantly improves the developer experience while maintaining security through the separation of read-only and write operations.
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
Changelog
For a detailed history of changes, new features, and bug fixes, see the CHANGELOG.md file.
Recent Updates
- v0.1.2: Added comprehensive Security Role Management system with 13 new tools
- v0.1.1: Introduced Solution-Based Architecture with persistent context
- v0.1.0: Initial release with core table, column, relationship, and option set operations
The changelog follows Keep a Changelog format and includes:
- Added: New features and capabilities
- Changed: Modifications to existing functionality
- Fixed: Bug fixes and corrections
- Security: Security-related updates
Releasing
This project includes automated release scripts for maintainers:
Creating a Release
These scripts will:
- Build the project
- Bump the version in
package.json
- Create a git tag
- Push the changes and tag to GitHub
Automated GitHub Releases
When a tag is pushed to GitHub, the GitHub Actions workflow will automatically:
- Build the project
- Create release archives (
.tar.gz
and.zip
) - Create a GitHub release with the archives attached
- Include installation instructions in the release notes
Manual Release Process
If you prefer to create releases manually:
- Build the project:
npm run build
- Update version:
npm version [patch|minor|major]
- Push changes:
git push && git push --tags
- The GitHub Actions workflow will handle the rest
License
MIT License - see LICENSE file for details.
Support
For issues and questions:
- Check the troubleshooting section
- Review Dataverse Web API documentation
- Create an issue in the repository
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Enables comprehensive Microsoft Dataverse schema management through the Dataverse Web API, supporting table/column operations, relationships, security roles, and PowerPages integration with enterprise-grade solution-based architecture.
- 🚀 Key Features
- Table of Contents
- Features
- Solution-Based Architecture
- Supported Column Types
- Testing & Quality Assurance
- Prerequisites
- Setup
- Installation
- Configuration
- Usage Examples
- Mermaid Diagram Generation
- PowerPages Configuration Management
- Authentication
- Error Handling
- Security Considerations
- Troubleshooting
- API Reference
- Solution Management Best Practices
- Developer Notebook
- Contributing
- Changelog
- Releasing
- License
- Support
Related MCP Servers
- AsecurityAlicenseAqualityAI assistants to query and analyze Azure Data Explorer databases through standardized interfaces.Last updated -445PythonMIT License
- -securityAlicense-qualityProvides database interaction and business intelligence capabilities, enabling users to run SQL queries, analyze business data, and automatically generate business insight memos for Microsoft SQL Server databases.Last updated -37PythonMIT License
- -securityAlicense-qualityMicrosoft Dataverse MCP Server by CDataLast updated -MIT License
- AsecurityFlicenseAqualityEnables interaction with Microsoft SQL Server databases through a Model Context Protocol interface, supporting database connections, switching between databases, and executing secure SELECT queries.Last updated -86JavaScript