Imported from mafzaal/d365fo-client (AGENTS.md). Install upstream with npx skills add mafzaal/d365fo-client. Copyright stays with the author.

AI Agent Guide for D365FO MCP Server

This guide is specifically designed for AI agents and assistants to effectively interact with Microsoft Dynamics 365 Finance & Operations through the d365fo-client MCP server. It provides structured workflows, best practices, and common patterns for successful automation and integration.

Architecture Overview

The d365fo-client MCP server provides 49 comprehensive tools organized across 9 functional categories, implemented using a modern FastMCP mixin-based architecture for enhanced performance and maintainability. All tools are available through standardized MCP protocol interactions regardless of the underlying implementation.

Quick Start for AI Agents

Essential First Steps

Test Connectivity: Always start with d365fo_test_connection to verify environment access
Get Environment Info: Use d365fo_get_environment_info to understand the D365FO environment capabilities
Explore Available Entities: Use d365fo_search_entities to discover relevant data entities for your tasks

// Step 1: Test connection
{
  "tool": "d365fo_test_connection",
  "arguments": {}
}

// Step 2: Get environment information
{
  "tool": "d365fo_get_environment_info",
  "arguments": {}
}

// Step 3: Search for relevant entities
{
  "tool": "d365fo_search_entities",
  "arguments": {
    "pattern": "customer",
    "limit": 10
  }
}

Core Workflows for AI Agents

1. Data Discovery and Exploration

Use Case: Understanding available data structures and relationships

// Discover entities by business area
{
  "tool": "d365fo_search_entities",
  "arguments": {
    "pattern": "sales|customer|invoice",
    "category": "Master",
    "limit": 20
  }
}

// Get detailed schema for specific entity
{
  "tool": "d365fo_get_entity_schema",
  "arguments": {
    "entityName": "CustomersV3",
    "includeProperties": true,
    "includeKeys": true,
    "resolveLabels": true
  }
}

// Search for related actions
{
  "tool": "d365fo_search_actions",
  "arguments": {
    "pattern": "customer",
    "limit": 10
  }
}

2. Data Querying and Analysis

Use Case: Retrieving and analyzing business data

// Query customers with filtering
{
  "tool": "d365fo_query_entities",
  "arguments": {
    "entityName": "CustomersV3",
    "select": ["CustomerAccount", "Name", "CustomerGroup", "Email"],
    "filter": "CustomerGroup eq 'VIP'",
    "top": 50
  }
}

// Get specific customer record
{
  "tool": "d365fo_get_entity_record",
  "arguments": {
    "entityName": "CustomersV3",
    "key": "US-001",
    "select": ["CustomerAccount", "Name", "Address", "ContactInfo"]
  }
}

// Query related sales orders
{
  "tool": "d365fo_query_entities",
  "arguments": {
    "entityName": "SalesOrderHeaders",
    "select": ["SalesOrderNumber", "CustomerAccount", "TotalAmount", "OrderDate"],
    "filter": "CustomerAccount eq 'US-001'",
    "orderby": "OrderDate desc",
    "top": 20
  }
}

3. Data Management Operations

Use Case: Creating, updating, and managing business records

// Create new customer
{
  "tool": "d365fo_create_entity_record",
  "arguments": {
    "entityName": "CustomersV3",
    "data": {
      "CustomerAccount": "US-999",
      "Name": "New Customer Corp",
      "CustomerGroup": "Standard",
      "Email": "contact@newcustomer.com"
    }
  }
}

// Update customer information
{
  "tool": "d365fo_update_entity_record",
  "arguments": {
    "entityName": "CustomersV3",
    "key": "US-999",
    "data": {
      "Email": "updated@newcustomer.com",
      "Name": "Updated Customer Corp"
    }
  }
}

// Execute business action
{
  "tool": "d365fo_call_action",
  "arguments": {
    "entityName": "CustomersV3",
    "actionName": "ValidateCustomer",
    "parameters": {
      "CustomerAccount": "US-999"
    }
  }
}

4. Metadata and System Management

Use Case: Understanding system configuration and capabilities

// Search system enumerations
{
  "tool": "d365fo_search_enumerations",
  "arguments": {
    "search": "status",
    "limit": 10
  }
}

// Get enumeration values
{
  "tool": "d365fo_get_enumeration_fields",
  "arguments": {
    "enumerationName": "CustVendorBlocked",
    "resolveLabels": true
  }
}

// Get installed modules
{
  "tool": "d365fo_get_installed_modules",
  "arguments": {}
}

5. Reporting and Document Management

Use Case: Generating and downloading business documents

// Download customer invoice
{
  "tool": "d365fo_download_customer_invoice",
  "arguments": {
    "invoiceId": "INV-001",
    "format": "PDF",
    "profile": "default"
  }
}

// Download sales confirmation
{
  "tool": "d365fo_download_sales_confirmation",
  "arguments": {
    "salesOrderNumber": "SO-001",
    "format": "PDF",
    "profile": "default"
  }
}

// Generate custom SRS report
{
  "tool": "d365fo_download_srs_report",
  "arguments": {
    "reportName": "CustomerStatement",
    "parameters": {
      "CustomerAccount": "US-001",
      "FromDate": "2024-01-01",
      "ToDate": "2024-12-31"
    },
    "format": "PDF"
  }
}

Advanced Patterns for AI Agents

Profile-Based Multi-Environment Operations

Use Case: Working with multiple D365FO environments (dev, test, prod)

// List available profiles
{
  "tool": "d365fo_list_profiles",
  "arguments": {}
}

// Test specific environment
{
  "tool": "d365fo_test_profile_connection",
  "arguments": {
    "profileName": "production"
  }
}

// Query data from specific environment
{
  "tool": "d365fo_query_entities",
  "arguments": {
    "entityName": "CustomersV3",
    "profile": "production",
    "top": 10
  }
}

Database Analysis and Insights

Use Case: Advanced data analysis and metadata exploration

// Get database schema overview
{
  "tool": "d365fo_get_database_schema",
  "arguments": {
    "includeEntityRelationships": true,
    "profile": "default"
  }
}

// Execute analytical queries
{
  "tool": "d365fo_execute_sql_query",
  "arguments": {
    "query": "SELECT name, entity_category, data_service_enabled FROM data_entities WHERE entity_category = 'Master' ORDER BY name LIMIT 20",
    "profile": "default"
  }
}

// Get performance statistics
{
  "tool": "d365fo_get_database_statistics",
  "arguments": {
    "includePerformanceMetrics": true,
    "profile": "default"
  }
}

Synchronization and Cache Management

Use Case: Managing metadata synchronization and cache optimization

// Start metadata sync
{
  "tool": "d365fo_start_sync",
  "arguments": {
    "strategy": "incremental",
    "profile": "default"
  }
}

// Monitor sync progress
{
  "tool": "d365fo_get_sync_progress",
  "arguments": {
    "sessionId": "sync-session-123",
    "profile": "default"
  }
}

// Get sync history
{
  "tool": "d365fo_get_sync_history",
  "arguments": {
    "limit": 10,
    "profile": "default"
  }
}

Best Practices for AI Agents

1. Error Handling and Resilience

Always check connection first: Use d365fo_test_connection before starting workflows
Handle authentication errors: Retry with different profiles if authentication fails
Validate entity names: Use d365fo_search_entities to verify entity existence before operations
Check for required fields: Use d365fo_get_entity_schema to understand mandatory fields before creating records

2. Performance Optimization

Use appropriate filters: Apply $filter parameters to reduce data transfer
Limit result sets: Always use top parameter for large queries
Select specific fields: Use select parameter to retrieve only needed columns
Cache metadata: Leverage the built-in metadata caching for repeated operations

3. Data Integrity

Validate before updates: Check existing record state before modifications
Use ETags for concurrency: Leverage optimistic concurrency control where available
Understand relationships: Use d365fo_get_entity_schema to understand foreign key relationships
Test in non-production: Always test complex operations in development environments first

4. Security and Compliance

Use appropriate profiles: Separate development, test, and production profiles
Validate permissions: Check that the current user has appropriate permissions for operations
Audit operations: Log significant data changes for compliance requirements
Secure credentials: Use profile-based authentication rather than embedding credentials

Common Integration Scenarios

Customer Relationship Management

// Complete customer onboarding workflow
[
  {
    "tool": "d365fo_search_entities",
    "arguments": {"pattern": "customer", "category": "Master"}
  },
  {
    "tool": "d365fo_get_entity_schema",
    "arguments": {"entityName": "CustomersV3", "includeProperties": true}
  },
  {
    "tool": "d365fo_create_entity_record",
    "arguments": {
      "entityName": "CustomersV3",
      "data": {
        "CustomerAccount": "NEW-001",
        "Name": "New Customer",
        "CustomerGroup": "Standard"
      }
    }
  },
  {
    "tool": "d365fo_get_entity_record",
    "arguments": {"entityName": "CustomersV3", "key": "NEW-001"}
  }
]

Financial Reporting

// Generate comprehensive financial report
[
  {
    "tool": "d365fo_query_entities",
    "arguments": {
      "entityName": "GeneralJournalEntries",
      "filter": "AccountingDate ge datetime'2024-01-01' and AccountingDate le datetime'2024-12-31'",
      "select": ["AccountNum", "TransactionAmount", "AccountingDate"],
      "top": 1000
    }
  },
  {
    "tool": "d365fo_download_srs_report",
    "arguments": {
      "reportName": "FinancialStatement",
      "parameters": {"FiscalYear": "2024"},
      "format": "PDF"
    }
  }
]

Supply Chain Management

// Inventory and procurement analysis
[
  {
    "tool": "d365fo_query_entities",
    "arguments": {
      "entityName": "InventoryOnHand",
      "select": ["ItemNumber", "AvailableQuantity", "WarehouseId"],
      "filter": "AvailableQuantity lt 10"
    }
  },
  {
    "tool": "d365fo_query_entities",
    "arguments": {
      "entityName": "PurchaseOrders",
      "filter": "PurchaseOrderStatus eq 'Open'",
      "select": ["PurchaseOrderNumber", "VendorAccount", "TotalAmount"]
    }
  }
]

Troubleshooting Guide for AI Agents

Common Issues and Solutions

Connection Failures

// Test with explicit timeout
{
  "tool": "d365fo_test_connection",
  "arguments": {"timeout": 120}
}

Entity Not Found Errors

// Search for similar entities
{
  "tool": "d365fo_search_entities",
  "arguments": {"pattern": "partial_name"}
}

Authentication Issues

// List and test profiles
{
  "tool": "d365fo_list_profiles",
  "arguments": {}
}

Data Validation Errors

// Get entity schema for validation rules
{
  "tool": "d365fo_get_entity_schema",
  "arguments": {"entityName": "EntityName", "includeProperties": true}
}

Performance Monitoring

// Monitor server performance
{
  "tool": "d365fo_get_server_performance",
  "arguments": {}
}

// Check database statistics
{
  "tool": "d365fo_get_database_statistics",
  "arguments": {"includePerformanceMetrics": true}
}

Tool Reference Quick Guide

Essential Tools for Every AI Agent

d365fo_test_connection - Always start here
d365fo_get_environment_info - Understand the environment
d365fo_search_entities - Discover available data
d365fo_query_entities - Primary data retrieval
d365fo_get_entity_schema - Understand data structures

Data Operations

d365fo_get_entity_record - Retrieve specific records
d365fo_create_entity_record - Create new records
d365fo_update_entity_record - Modify existing records
d365fo_delete_entity_record - Remove records
d365fo_call_action - Execute business logic

Advanced Operations

d365fo_execute_sql_query - Custom analytical queries
d365fo_download_srs_report - Generate reports
d365fo_start_sync - Manage metadata synchronization
d365fo_get_labels_batch - Multi-language support

Profile Management

d365fo_list_profiles - See available environments
d365fo_test_profile_connection - Validate environment access
d365fo_create_profile - Set up new environments

Success Patterns

Start Small: Begin with simple queries before complex operations
Understand the Schema: Always explore entity schemas before data operations
Use Filters Wisely: Apply appropriate filters to manage data volume
Test Incrementally: Validate each step of complex workflows
Monitor Performance: Use performance tools to optimize operations
Handle Errors Gracefully: Implement robust error handling and recovery
Document Workflows: Keep track of successful patterns for reuse

This guide provides AI agents with the knowledge and patterns needed to effectively leverage the full capabilities of the D365FO MCP server for automation, integration, and analysis tasks.

d365fo-client

About