Ghcopilot Instr Power Platform Mcp Development

---
name: ghcopilot-instr-power-platform-mcp-development
description: Instructions for developing Power Platform custom connectors with Model Context Protocol (MCP) integration for Microsoft Copilot Studio. Use when writing or reviewing power platform mcp development code and need idiomatic conventions and best practices.
license: CC-BY-NC-SA-4.0
metadata:
  version: "1.0.0"
  tags: [copilot-instruction, community, power-platform-mcp-development]
  applyTo: "**/*.{json,csx,md}"
  source: "awesome-copilot"
---

# Power Platform MCP Custom Connector Development

## Instructions

### MCP Protocol Integration
- Always implement JSON-RPC 2.0 standard for MCP communication
- Use `x-ms-agentic-protocol: mcp-streamable-1.0` header for Copilot Studio compatibility
- Structure endpoints to support both standard REST operations and MCP tool invocation
- Transform responses to comply with Copilot Studio constraints (no reference types, single types only)

### Schema Design Best Practices
- Remove `$ref` and other reference types from JSON schemas as Copilot Studio cannot handle them
- Use single types instead of arrays of types in schema definitions
- Flatten `anyOf`/`oneOf` constructs to single schemas for Copilot Studio compatibility
- Ensure all tool input schemas are self-contained without external references

### Authentication and Security
- Implement OAuth 2.0 with MCP security best practices within Power Platform constraints
- Use connection parameter sets for flexible authentication configuration
- Validate token audience to prevent passthrough attacks
- Add MCP-specific security headers for enhanced validation
- Support multiple authentication methods (OAuth standard, OAuth enhanced, API key fallback)

### Custom Script Implementation
- Handle JSON-RPC transformation in the custom script (script.csx)
- Implement proper error handling with JSON-RPC error response format
- Add token validation and audience checking in authentication flow
- Transform MCP server responses for Copilot Studio compatibility
- Use connection parameters for dynamic security configuration

### Swagger Definition Guidelines
- Use Swagger 2.0 specification for Power Platform compatibility
- Implement proper `operationId` values for each endpoint
- Define clear parameter schemas with appropriate types and descriptions
- Add comprehensive response schemas for all success and error cases
- Include proper HTTP status codes and response headers

### Resource and Tool Management
- Structure MCP resources to be consumable as tool outputs in Copilot Studio
- Ensure proper MIME type declarations for resource content
- Add audience and priority annotations for better Copilot Studio integration
- Implement resource transformation to meet Copilot Studio requirements

### Connection Parameter Configuration
- Use enum dropdowns for OAuth version and security level selection
- Provide clear parameter descriptions and constraints
- Support multiple authentication parameter sets for different deployment scenarios
- Include validation rules and default values where appropriate
- Enable dynamic configuration through connection parameter values

### Error Handling and Logging
- Implement comprehensive error responses following JSON-RPC 2.0 error format
- Add detailed logging for authentication, validation, and transformation steps
- Provide clear error messages that help with troubleshooting
- Include proper HTTP status codes aligned with error conditions

### Testing and Validation
- Test connector with actual MCP server implementations
- Validate schema transformations work correctly with Copilot Studio
- Verify authentication flows for all supported parameter sets
- Ensure proper error handling for various failure scenarios
- Test connection parameter configurations and dynamic behavior

## Additional Guidelines

### Power Platform Certification Requirements
- Include comprehensive documentation (readme.md, CUSTOMIZE.md)
- Provide clear setup and configuration instructions
- Document all authentication options and security considerations
- Include proper publisher and stack owner information
- Ensure compliance with Power Platform connector certification standards

### MCP Server Compatibility
- Design for compatibility with standard MCP server implementations
- Support common MCP methods like `tools/list`, `tools/call`, `resources/list`
- Handle streaming responses appropriately for `mcp-streamable-1.0` protocol
- Implement proper protocol negotiation and capability detection

### Copilot Studio Integration
- Ensure tool definitions work correctly within Copilot Studio's constraints
- Test resource access and tool invocation from Copilot Studio interface
- Validate that transformed schemas produce expected behavior in conversations
- Confirm proper integration with Copilot Studio's agent framework