id: power-platform-mcp-connector-development
name: Power Platform MCP Connector Development
description: Complete toolkit for developing Power Platform custom connectors with Model Context Protocol integration for Microsoft Copilot Studio
tags: 
  - power-platform
  - mcp
  - copilot-studio
  - custom-connector
  - json-rpc
items:
  - path: ../instructions/power-platform-mcp-development.instructions.md
    kind: instruction
  - path: ../prompts/power-platform-mcp-connector-suite.prompt.md
    kind: prompt
  - path: ../prompts/mcp-copilot-studio-server-generator.prompt.md
    kind: prompt
  - path: ../chatmodes/power-platform-mcp-integration-expert.chatmode.md
    kind: chat-mode
display:
  ordering: manual
  show_badge: true

overview: |
  A comprehensive collection for building Power Platform custom connectors with 
  Model Context Protocol (MCP) integration for Microsoft Copilot Studio.
  
  This collection addresses the specific constraints and requirements of Copilot 
  Studio MCP integration while leveraging proven patterns from successful 
  implementations like the National Weather Service connector.

key_patterns:
  mcp_protocol:
    - Streamable HTTP with x-ms-agentic-protocol mcp-streamable-1.0
    - JSON-RPC 2.0 compliant request/response handling
    - Tools and Resources supported (Prompts not yet supported in Copilot Studio)
    - No reference types in schemas (filtered by Copilot Studio)
    - Single types only (not arrays of multiple types)
    - Resources as tool outputs, not separate entities
    - Full URIs required for all endpoints
    - OAuth 2.0/2.1 hybrid authentication support
    - MCP security best practices implementation

  copilot_studio_constraints:
    - Tools with reference type inputs are filtered
    - Enum inputs interpreted as strings
    - Generative Orchestration must be enabled
    - Resources must be tool outputs to be accessible

  power_platform_integration:
    - Traditional REST endpoints can coexist with MCP
    - Proper apiDefinition.swagger.json with Microsoft extensions
    - apiProperties.json for authentication and metadata
    - Policy templates for data transformation
    - Connector certification workflows
    
  oauth_security_patterns:
    - OAuth 2.0 standard for Power Platform and Copilot Studio
    - Enhanced security through custom script implementation
    - Token audience validation to prevent passthrough attacks
    - MCP security best practices within OAuth 2.0 framework
    - State parameter protection for CSRF prevention
    - Secure token handling and scope validation
    
  mcp_security_best_practices:
    - Token audience validation prevents confused deputy attacks
    - No token passthrough to downstream services
    - Secure session management with non-deterministic IDs
    - HTTPS enforcement for all production endpoints
    - Custom script implementation of MCP security requirements
    - OAuth 2.0 enhanced with MCP-level security validations

workflows:
  new_connector_development:
    - Use power-platform-mcp-connector-suite.prompt.md with Mode 1 (Complete New Connector)
    - Consult power-platform-mcp-integration-expert.chatmode.md for implementation guidance
    - Validate with paconn CLI and ConnectorPackageValidator.ps1
    - Deploy using pac CLI with automated script validation
    - Follow power-platform-connector.instructions.md for deployment
    - Test integration with Copilot Studio

  existing_connector_enhancement:
    - Use power-platform-mcp-connector-suite.prompt.md with Mode 4 (Hybrid Connector)
    - Work with power-platform-mcp-integration-expert.chatmode.md for integration strategy
    - Validate enhancements with CLI tools
    - Follow power-platform-connector.instructions.md for compliance

  schema_validation_and_troubleshooting:
    - Use power-platform-mcp-connector-suite.prompt.md with Mode 2 (Schema Validation) or Mode 3 (Troubleshooting)
    - Leverage power-platform-mcp-integration-expert.chatmode.md for complex issues
    - Run comprehensive validation using Microsoft's official tools
    - Validate against power-platform-connector.instructions.md requirements

  certification_preparation:
    - Use power-platform-mcp-connector-suite.prompt.md with Mode 5 (Certification)
    - Complete product and service metadata requirements
    - Run ConnectorPackageValidator.ps1 for certification compliance
    - Prepare documentation and testing evidence
    - Submit through Microsoft partner portal

success_criteria:
  - Tools appear in Copilot Studio agent tool list
  - Resources accessible through tool outputs
  - JSON-RPC 2.0 communication works reliably
  - Schema validation passes without reference type errors
  - Dynamic tool discovery updates automatically
  - Authentication and authorization work correctly
  - Performance meets enterprise requirements

cli_tools:
  paconn:
    purpose: Swagger validation and connector package management
    installation: pip install paconn
    usage: paconn validate --api-def apiDefinition.swagger.json
    
  pac:
    purpose: Connector creation, updates, and script validation
    installation: winget install Microsoft.PowerPlatformCLI
    usage: pac connector create --settings-file connector-settings.json
    
  connector_package_validator:
    purpose: Microsoft's official certification validation
    source: https://github.com/microsoft/PowerPlatformConnectors/blob/dev/scripts/ConnectorPackageValidator.ps1
    usage: .\ConnectorPackageValidator.ps1 -ConnectorPath "." -Verbose

certification_requirements:
  required_files:
    - apiDefinition.swagger.json
    - apiProperties.json
    - script.csx (optional but validated when uploaded)
    - icon.png (230x230 or 500x500 PNG)
    - readme.md
    - settings.json (product and service metadata)
  
  metadata_compliance:
    - Complete product and service information
    - Privacy policy and support URLs
    - Compliance standards (SOC2, GDPR, etc.)
    - Authentication and security details
    - Pricing and data location information

best_practices:
  schema_design:
    - Start with Copilot Studio constraints
    - Use primitive types with validation logic in implementation
    - Embed resources in tool outputs with proper structure
    - Plan for schema evolution and backward compatibility
  
  development_process:
    - Validate schemas early and often using CLI tools
    - Test with real Copilot Studio agents during development
    - Implement comprehensive error handling and logging
    - Use proven patterns from successful connectors
    - Run ConnectorPackageValidator.ps1 before deployment
  
  integration_strategy:
    - Enable Generative Orchestration in Copilot Studio
    - Configure OAuth 2.0 authentication with MCP security enhancements
    - Implement MCP security best practices from day one
    - Validate token audience to prevent security vulnerabilities
    - Monitor tool usage and performance metrics
    - Plan for scaling and enterprise deployment
    - Prepare for certification submission early in development
    - Test OAuth 2.0 flows with enhanced MCP security validation