Power Platform MCP connector suite
Generate complete Power Platform custom connector assets for MCP integration in Microsoft Copilot Studio, then validate schema, authentication, JSON-RPC handling, and deployment readiness.
When to invoke
- "Create a Microsoft Copilot Studio custom connector for my MCP server."
- "Validate this Power Platform connector schema for MCP tools."
- "Troubleshoot why Microsoft Copilot Studio filtered my MCP tools."
- "Add MCP capabilities to an existing connector."
- "Prepare this MCP connector for Microsoft certification."
MCP support model
| Capability |
Microsoft Copilot Studio support |
Implementation rule |
| Tools |
Supported |
Expose callable functions through the MCP endpoint with user approval semantics. |
| Resources |
Supported as tool outputs |
Return file-like data through tools; do not model resources as separate top-level entities. |
| Prompts |
Not yet supported |
Do not emit prompt entities; leave the connector structure ready for future support only if requested. |
Connector assets
| File |
Required content |
apiDefinition.swagger.json |
Swagger 2.0, POST /mcp, full URI endpoints, x-ms-agentic-protocol: mcp-streamable-1.0, primitive-only schemas, McpResponse, and McpErrorResponse. |
apiProperties.json |
Connector metadata, iconBrandColor, authentication, policy templates for MCP request/response transformations. |
script.csx |
C# transformations for JSON-RPC 2.0 messages, MCP protocol compliance, error handling, token checks, and request/response shaping. |
readme.md |
Connector purpose, setup, examples, Microsoft Copilot Studio integration steps, validation commands, and troubleshooting. |
settings.json |
Product and service metadata for certification preparation when requested. |
Schema compliance rules
| Rule |
Why it matters |
Fix |
No $ref in tool inputs or outputs |
Microsoft Copilot Studio filters tools with unsupported reference types. |
Inline schema shapes with primitive properties. |
| Single type values only |
Type arrays such as ["string", "number"] are rejected. |
Use one of string, number, integer, boolean, array, or object and validate alternatives in script.csx. |
| Resources are tool outputs |
Microsoft Copilot Studio supports Resources through tool calls. |
Add resource payloads to the corresponding tool response. |
| Full URI endpoints |
Connector import and runtime need resolvable endpoints. |
Emit absolute URLs for host operations and callback references. |
| JSON-RPC 2.0 compliance |
MCP calls must preserve jsonrpc, id, method, params, result, and error semantics. |
Validate envelopes in script.csx and emit McpErrorResponse for failures. |
| Generative Orchestration compatibility |
Agents need clear tool descriptions and predictable schemas. |
Write concise descriptions and avoid polymorphic input contracts. |
Generation modes
| Mode |
Use when |
Produce |
| Complete New Connector |
Starting from server purpose, tools, resources, and auth. |
All core files plus validation guidance. |
| Schema Validation |
Existing Swagger or connector fails import or tools are missing. |
Finding list and patched schema recommendations. |
| Integration Troubleshooting |
Runtime calls fail in Microsoft Copilot Studio. |
Diagnosis across protocol header, JSON-RPC, auth, endpoint URI, and resource shape. |
| Hybrid Connector |
Existing Power Platform connector needs MCP endpoint. |
Minimal additive changes while preserving existing operations. |
| Certification Preparation |
Connector is headed for Microsoft certification. |
Metadata, icon, documentation, privacy, validation, and security checklist. |
| OAuth Security Hardening |
OAuth 2.0 connector handles MCP calls. |
Audience validation, state protection, HTTPS enforcement, and confused deputy prevention. |
Inputs
Collect these context variables before generating files. Ask for missing required values or use placeholders only in a planning output, never in final connector JSON.
| Variable |
Meaning |
| Connector Name |
Display name for the connector. |
| Server Purpose |
What the MCP server accomplishes. |
| Tools Needed |
MCP tools to expose. |
| Resources |
Resource payloads returned by tools. |
| Authentication |
none, api-key, oauth2, or basic. |
| Host Environment |
Azure Function, Express.js, or another HTTP host. |
| Target APIs |
External APIs the MCP server integrates with. |
Validation and security
| Area |
Check |
| paconn |
paconn validate --api-def apiDefinition.swagger.json passes without errors. |
| pac CLI |
Connector can be created or updated with pac connector create or pac connector update. |
| Script upload |
script.csx passes automatic validation during PAC CLI upload. |
| Package validation |
ConnectorPackageValidator.ps1 runs successfully when preparing certification. |
| OAuth 2.0 |
Use standard OAuth 2.0 plus MCP audience validation to prevent passthrough attacks. |
| CSRF |
Protect OAuth state parameters. |
| HTTPS |
Production endpoints use HTTPS only. |
| Auth config |
Authentication type, token handling, and custom security logic match the selected mode. |
| Certification |
settings.json, PNG icon in 230x230 or 500x500, privacy policy, and documentation are complete. |
Troubleshooting
| Symptom |
Likely cause |
Resolution |
| Tools filtered |
$ref or unsupported schema shape in inputs/outputs. |
Inline schemas and use primitive single types. |
| Type errors |
Multi-type values or polymorphic fields. |
Use one type and validate alternatives in script.csx. |
| Resources unavailable |
Resources modeled separately. |
Return resources as tool outputs. |
| Connection failures |
Missing or wrong x-ms-agentic-protocol value or non-full URI. |
Set x-ms-agentic-protocol: mcp-streamable-1.0 on POST /mcp and verify endpoint URLs. |
| OAuth works but wrong tenant/resource is accepted |
Missing token audience validation. |
Add enhanced validation in script.csx. |
Compatibility terminology
Preserve these baseline terms when they appear in user input, existing files, logs, or migration output; they are included to keep legacy wording, commands, paths, and API names recognizable during execution.
McpResponse/McpErrorResponsePOST /mcpRESTRequest/responsecreated/updatedinputs/outputs
Output template
## Power Platform MCP connector — <Connector Name>
**Status:** generated | validation fixes required | blocked
**Mode:** Complete New Connector | Schema Validation | Integration Troubleshooting | Hybrid Connector | Certification Preparation | OAuth Security Hardening
### Files
| File | Status | Notes |
| --- | --- | --- |
| `apiDefinition.swagger.json` | <created/updated/planned> | <MCP endpoint and schema notes> |
| `apiProperties.json` | <created/updated/planned> | <auth and metadata notes> |
| `script.csx` | <created/updated/planned> | <JSON-RPC and security notes> |
| `readme.md` | <created/updated/planned> | <setup and examples> |
### Validation
- `paconn validate --api-def apiDefinition.swagger.json`: <pass/fail/not run>
- `pac connector create/update`: <ready/not ready>
- `ConnectorPackageValidator.ps1`: <pass/fail/not run>
### Open decisions
- <missing endpoint, auth, tool, resource, or certification decision>
Quality gate
1---2name: power-platform-mcp-connector-suite-33description: Generate and validate Power Platform custom connectors that expose Model Context Protocol servers to Microsoft Microsoft Copilot Studio, including Swagger, apiProperties.json, script.csx, JSON-RPC 2.0 handling, schema compliance, OAuth hardening, certification preparation, and troubleshooting. Use when asked for MCP capabilities in Microsoft Copilot Studio, a custom connector for MCP tools/resources, or paconn/pac connector validation.4---56<!-- Generated from harness/github-copilot/plugins/power-platform-mcp-connector-development/skills/power-platform-mcp-connector-suite/SKILL.md by harness/claude-code/scripts/convert_from_copilot.py. Edit the source, not this file. -->78# Power Platform MCP connector suite910Generate complete Power Platform custom connector assets for MCP integration in Microsoft Copilot Studio, then validate schema, authentication, JSON-RPC handling, and deployment readiness.1112## When to invoke1314- "Create a Microsoft Copilot Studio custom connector for my MCP server."15- "Validate this Power Platform connector schema for MCP tools."16- "Troubleshoot why Microsoft Copilot Studio filtered my MCP tools."17- "Add MCP capabilities to an existing connector."18- "Prepare this MCP connector for Microsoft certification."1920## MCP support model2122| Capability | Microsoft Copilot Studio support | Implementation rule |23| --- | --- | --- |24| Tools | Supported | Expose callable functions through the MCP endpoint with user approval semantics. |25| Resources | Supported as tool outputs | Return file-like data through tools; do not model resources as separate top-level entities. |26| Prompts | Not yet supported | Do not emit prompt entities; leave the connector structure ready for future support only if requested. |2728## Connector assets2930| File | Required content |31| --- | --- |32| `apiDefinition.swagger.json` | Swagger 2.0, POST `/mcp`, full URI endpoints, `x-ms-agentic-protocol: mcp-streamable-1.0`, primitive-only schemas, `McpResponse`, and `McpErrorResponse`. |33| `apiProperties.json` | Connector metadata, `iconBrandColor`, authentication, policy templates for MCP request/response transformations. |34| `script.csx` | C# transformations for JSON-RPC 2.0 messages, MCP protocol compliance, error handling, token checks, and request/response shaping. |35| `readme.md` | Connector purpose, setup, examples, Microsoft Copilot Studio integration steps, validation commands, and troubleshooting. |36| `settings.json` | Product and service metadata for certification preparation when requested. |3738## Schema compliance rules3940| Rule | Why it matters | Fix |41| --- | --- | --- |42| No `$ref` in tool inputs or outputs | Microsoft Copilot Studio filters tools with unsupported reference types. | Inline schema shapes with primitive properties. |43| Single type values only | Type arrays such as `["string", "number"]` are rejected. | Use one of `string`, `number`, `integer`, `boolean`, `array`, or `object` and validate alternatives in `script.csx`. |44| Resources are tool outputs | Microsoft Copilot Studio supports Resources through tool calls. | Add resource payloads to the corresponding tool response. |45| Full URI endpoints | Connector import and runtime need resolvable endpoints. | Emit absolute URLs for host operations and callback references. |46| JSON-RPC 2.0 compliance | MCP calls must preserve `jsonrpc`, `id`, `method`, `params`, `result`, and `error` semantics. | Validate envelopes in `script.csx` and emit `McpErrorResponse` for failures. |47| Generative Orchestration compatibility | Agents need clear tool descriptions and predictable schemas. | Write concise descriptions and avoid polymorphic input contracts. |4849## Generation modes5051| Mode | Use when | Produce |52| --- | --- | --- |53| Complete New Connector | Starting from server purpose, tools, resources, and auth. | All core files plus validation guidance. |54| Schema Validation | Existing Swagger or connector fails import or tools are missing. | Finding list and patched schema recommendations. |55| Integration Troubleshooting | Runtime calls fail in Microsoft Copilot Studio. | Diagnosis across protocol header, JSON-RPC, auth, endpoint URI, and resource shape. |56| Hybrid Connector | Existing Power Platform connector needs MCP endpoint. | Minimal additive changes while preserving existing operations. |57| Certification Preparation | Connector is headed for Microsoft certification. | Metadata, icon, documentation, privacy, validation, and security checklist. |58| OAuth Security Hardening | OAuth 2.0 connector handles MCP calls. | Audience validation, state protection, HTTPS enforcement, and confused deputy prevention. |5960## Inputs6162Collect these context variables before generating files. Ask for missing required values or use placeholders only in a planning output, never in final connector JSON.6364| Variable | Meaning |65| --- | --- |66| Connector Name | Display name for the connector. |67| Server Purpose | What the MCP server accomplishes. |68| Tools Needed | MCP tools to expose. |69| Resources | Resource payloads returned by tools. |70| Authentication | `none`, `api-key`, `oauth2`, or `basic`. |71| Host Environment | Azure Function, Express.js, or another HTTP host. |72| Target APIs | External APIs the MCP server integrates with. |7374## Validation and security7576| Area | Check |77| --- | --- |78| paconn | `paconn validate --api-def apiDefinition.swagger.json` passes without errors. |79| pac CLI | Connector can be created or updated with `pac connector create` or `pac connector update`. |80| Script upload | `script.csx` passes automatic validation during PAC CLI upload. |81| Package validation | `ConnectorPackageValidator.ps1` runs successfully when preparing certification. |82| OAuth 2.0 | Use standard OAuth 2.0 plus MCP audience validation to prevent passthrough attacks. |83| CSRF | Protect OAuth state parameters. |84| HTTPS | Production endpoints use HTTPS only. |85| Auth config | Authentication type, token handling, and custom security logic match the selected mode. |86| Certification | `settings.json`, PNG icon in 230x230 or 500x500, privacy policy, and documentation are complete. |8788## Troubleshooting8990| Symptom | Likely cause | Resolution |91| --- | --- | --- |92| Tools filtered | `$ref` or unsupported schema shape in inputs/outputs. | Inline schemas and use primitive single types. |93| Type errors | Multi-type values or polymorphic fields. | Use one type and validate alternatives in `script.csx`. |94| Resources unavailable | Resources modeled separately. | Return resources as tool outputs. |95| Connection failures | Missing or wrong `x-ms-agentic-protocol` value or non-full URI. | Set `x-ms-agentic-protocol: mcp-streamable-1.0` on POST `/mcp` and verify endpoint URLs. |96| OAuth works but wrong tenant/resource is accepted | Missing token audience validation. | Add enhanced validation in `script.csx`. |9798## Compatibility terminology99100Preserve these baseline terms when they appear in user input, existing files, logs, or migration output; they are included to keep legacy wording, commands, paths, and API names recognizable during execution.101102- `McpResponse/McpErrorResponse`103- `POST /mcp`104- `REST`105- `Request/response`106- `created/updated`107- `inputs/outputs`108109## Output template110111```markdown112## Power Platform MCP connector — <Connector Name>113114**Status:** generated | validation fixes required | blocked115**Mode:** Complete New Connector | Schema Validation | Integration Troubleshooting | Hybrid Connector | Certification Preparation | OAuth Security Hardening116117### Files118| File | Status | Notes |119| --- | --- | --- |120| `apiDefinition.swagger.json` | <created/updated/planned> | <MCP endpoint and schema notes> |121| `apiProperties.json` | <created/updated/planned> | <auth and metadata notes> |122| `script.csx` | <created/updated/planned> | <JSON-RPC and security notes> |123| `readme.md` | <created/updated/planned> | <setup and examples> |124125### Validation126- `paconn validate --api-def apiDefinition.swagger.json`: <pass/fail/not run>127- `pac connector create/update`: <ready/not ready>128- `ConnectorPackageValidator.ps1`: <pass/fail/not run>129130### Open decisions131- <missing endpoint, auth, tool, resource, or certification decision>132```133134## Quality gate135136- [ ] POST `/mcp` uses `x-ms-agentic-protocol: mcp-streamable-1.0`.137- [ ] Tool input/output schemas contain no `$ref` and no multi-type arrays.138- [ ] Resources are represented as tool outputs; Prompts are not emitted as supported runtime entities.139- [ ] `McpResponse`, `McpErrorResponse`, and JSON-RPC 2.0 envelope handling are covered.140- [ ] Auth configuration includes HTTPS, state protection, and token audience validation when OAuth 2.0 is used.141- [ ] Validation commands and certification requirements are reported with pass/fail/not-run status.
paulasilvatech