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-23description: 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# Power Platform MCP connector suite78Generate complete Power Platform custom connector assets for MCP integration in Microsoft Copilot Studio, then validate schema, authentication, JSON-RPC handling, and deployment readiness.910## When to invoke1112- "Create a Microsoft Copilot Studio custom connector for my MCP server."13- "Validate this Power Platform connector schema for MCP tools."14- "Troubleshoot why Microsoft Copilot Studio filtered my MCP tools."15- "Add MCP capabilities to an existing connector."16- "Prepare this MCP connector for Microsoft certification."1718## MCP support model1920| Capability | Microsoft Copilot Studio support | Implementation rule |21| --- | --- | --- |22| Tools | Supported | Expose callable functions through the MCP endpoint with user approval semantics. |23| Resources | Supported as tool outputs | Return file-like data through tools; do not model resources as separate top-level entities. |24| Prompts | Not yet supported | Do not emit prompt entities; leave the connector structure ready for future support only if requested. |2526## Connector assets2728| File | Required content |29| --- | --- |30| `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`. |31| `apiProperties.json` | Connector metadata, `iconBrandColor`, authentication, policy templates for MCP request/response transformations. |32| `script.csx` | C# transformations for JSON-RPC 2.0 messages, MCP protocol compliance, error handling, token checks, and request/response shaping. |33| `readme.md` | Connector purpose, setup, examples, Microsoft Copilot Studio integration steps, validation commands, and troubleshooting. |34| `settings.json` | Product and service metadata for certification preparation when requested. |3536## Schema compliance rules3738| Rule | Why it matters | Fix |39| --- | --- | --- |40| No `$ref` in tool inputs or outputs | Microsoft Copilot Studio filters tools with unsupported reference types. | Inline schema shapes with primitive properties. |41| 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`. |42| Resources are tool outputs | Microsoft Copilot Studio supports Resources through tool calls. | Add resource payloads to the corresponding tool response. |43| Full URI endpoints | Connector import and runtime need resolvable endpoints. | Emit absolute URLs for host operations and callback references. |44| 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. |45| Generative Orchestration compatibility | Agents need clear tool descriptions and predictable schemas. | Write concise descriptions and avoid polymorphic input contracts. |4647## Generation modes4849| Mode | Use when | Produce |50| --- | --- | --- |51| Complete New Connector | Starting from server purpose, tools, resources, and auth. | All core files plus validation guidance. |52| Schema Validation | Existing Swagger or connector fails import or tools are missing. | Finding list and patched schema recommendations. |53| Integration Troubleshooting | Runtime calls fail in Microsoft Copilot Studio. | Diagnosis across protocol header, JSON-RPC, auth, endpoint URI, and resource shape. |54| Hybrid Connector | Existing Power Platform connector needs MCP endpoint. | Minimal additive changes while preserving existing operations. |55| Certification Preparation | Connector is headed for Microsoft certification. | Metadata, icon, documentation, privacy, validation, and security checklist. |56| OAuth Security Hardening | OAuth 2.0 connector handles MCP calls. | Audience validation, state protection, HTTPS enforcement, and confused deputy prevention. |5758## Inputs5960Collect these context variables before generating files. Ask for missing required values or use placeholders only in a planning output, never in final connector JSON.6162| Variable | Meaning |63| --- | --- |64| Connector Name | Display name for the connector. |65| Server Purpose | What the MCP server accomplishes. |66| Tools Needed | MCP tools to expose. |67| Resources | Resource payloads returned by tools. |68| Authentication | `none`, `api-key`, `oauth2`, or `basic`. |69| Host Environment | Azure Function, Express.js, or another HTTP host. |70| Target APIs | External APIs the MCP server integrates with. |7172## Validation and security7374| Area | Check |75| --- | --- |76| paconn | `paconn validate --api-def apiDefinition.swagger.json` passes without errors. |77| pac CLI | Connector can be created or updated with `pac connector create` or `pac connector update`. |78| Script upload | `script.csx` passes automatic validation during PAC CLI upload. |79| Package validation | `ConnectorPackageValidator.ps1` runs successfully when preparing certification. |80| OAuth 2.0 | Use standard OAuth 2.0 plus MCP audience validation to prevent passthrough attacks. |81| CSRF | Protect OAuth state parameters. |82| HTTPS | Production endpoints use HTTPS only. |83| Auth config | Authentication type, token handling, and custom security logic match the selected mode. |84| Certification | `settings.json`, PNG icon in 230x230 or 500x500, privacy policy, and documentation are complete. |8586## Troubleshooting8788| Symptom | Likely cause | Resolution |89| --- | --- | --- |90| Tools filtered | `$ref` or unsupported schema shape in inputs/outputs. | Inline schemas and use primitive single types. |91| Type errors | Multi-type values or polymorphic fields. | Use one type and validate alternatives in `script.csx`. |92| Resources unavailable | Resources modeled separately. | Return resources as tool outputs. |93| 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. |94| OAuth works but wrong tenant/resource is accepted | Missing token audience validation. | Add enhanced validation in `script.csx`. |9596## Compatibility terminology9798Preserve 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.99100- `McpResponse/McpErrorResponse`101- `POST /mcp`102- `REST`103- `Request/response`104- `created/updated`105- `inputs/outputs`106107## Output template108109```markdown110## Power Platform MCP connector — <Connector Name>111112**Status:** generated | validation fixes required | blocked113**Mode:** Complete New Connector | Schema Validation | Integration Troubleshooting | Hybrid Connector | Certification Preparation | OAuth Security Hardening114115### Files116| File | Status | Notes |117| --- | --- | --- |118| `apiDefinition.swagger.json` | <created/updated/planned> | <MCP endpoint and schema notes> |119| `apiProperties.json` | <created/updated/planned> | <auth and metadata notes> |120| `script.csx` | <created/updated/planned> | <JSON-RPC and security notes> |121| `readme.md` | <created/updated/planned> | <setup and examples> |122123### Validation124- `paconn validate --api-def apiDefinition.swagger.json`: <pass/fail/not run>125- `pac connector create/update`: <ready/not ready>126- `ConnectorPackageValidator.ps1`: <pass/fail/not run>127128### Open decisions129- <missing endpoint, auth, tool, resource, or certification decision>130```131132## Quality gate133134- [ ] POST `/mcp` uses `x-ms-agentic-protocol: mcp-streamable-1.0`.135- [ ] Tool input/output schemas contain no `$ref` and no multi-type arrays.136- [ ] Resources are represented as tool outputs; Prompts are not emitted as supported runtime entities.137- [ ] `McpResponse`, `McpErrorResponse`, and JSON-RPC 2.0 envelope handling are covered.138- [ ] Auth configuration includes HTTPS, state protection, and token audience validation when OAuth 2.0 is used.139- [ ] Validation commands and certification requirements are reported with pass/fail/not-run status.
paulasilvatech