Connecting Copilot Studio to an MCP Server via On-Premises Data Gateway (Stateless & API Key)

🚀 Guide: Connecting Copilot Studio to an MCP Server via On-Premises Data Gateway (Stateless & API Key)

If you are trying to integrate Copilot Studio with a local MCP (Model Context Protocol) Server and your infrastructure forces you to route traffic through an On-Premises Data Gateway due to corporate network restrictions, you will likely face critical configuration challenges and the dreaded SystemError code.

Here is a breakdown of the security UI bug, the exact Swagger design, caching latency, and the definitive method to detect if your testing environment has become corrupted.

🔐 1. The Core Issue: Missing "API Key" Option in Gateway Mode

The first obstacle occurs in the Security tab of your Custom Connector:

Normal Behavior: Without a gateway, the Power Apps interface natively allows you to select "API Key" authentication.
The UI Bug: As soon as you check the "Connect via on-premises data gateway" box, the API Key option completely disappears from the available authentication types.
⚠️ Warning: If you try to use any other workaround in the security tab to force a key requirement, the connector will immediately throw a Bad Request error when trying to establish or use the connection.
✨ The Solution: Infiltration via Policy

To solve this cleanly, set the security configuration to "No authentication" and inject your token using a transformation rule:

Go to 3. Definition > Policies > + New policy.
Select the Set HTTP header template.
Crucial: Set the Run policy on parameter strictly to Request.
Define your auth header name (e.g., x-api-key) and place your token in the value field.

🛠️ 2. Strict Swagger / OpenAPI Configuration

For this synchronous scenario through the local Gateway, your MCP server endpoint must natively support the Stateless protocol. Keep your Swagger minimal; additional headers like Accept or Content-Type are completely optional and shouldn't be added if your base architecture does not strictly require them.

Use this clean skeletal structure in your Swagger editor:

swagger: '2.0'
info:
  title: MCP Server
  description: Exposes MCP capabilities to AI agents via synchronous requests.
  version: 1.0.0
host: your-local-mcp-server.net:8446
basePath: /
schemes:
  - https
paths:
  /your-stateless-mcp-endpoint:
    post:
      responses:
        '200':
          description: Immediate Response
      x-ms-agentic-protocol: mcp-streamable-1.0
      operationId: InvokeServer
      summary: MCP Server
      description: Sends MCP messages to the server using the streamable/stateless protocol.
securityDefinitions: {}
security: []

⏳ 3. CRITICAL TIP: Custom Connector Replication Latency

A hidden trap that frustrates many developers is testing changes immediately after clicking save.

Custom Connector deployment across the Gateway is NOT instantaneous. When you save your Swagger or Policies in Power Apps, the platform updates the central repository, but the API Gateway and Copilot Studio take a considerable amount of time to purge their internal cache.

If you link the connector immediately to your agent, you will likely be interacting with an old cached version, making it seem like your fixes didn't work.

💡 Best Practices:

Wait a few minutes after saving changes before testing the bot.
To force a refresh, go to your environment connections, delete the active connection for that specific connector, remove the action from Copilot Studio, and recreate the link from scratch.

⚠️ 4. The Diagnostic Key: How to Spot a Corrupted Agent

During development, you will iterate frequently. The major risk with Copilot Studio is that the agent's test chat environment can have its metadata cache permanently corrupted, making the SystemError persist even if your Custom Connector and Swagger are now flawless.

🔍 The Isolation Test Method

If you have applied the correct fixes and the replication time has passed, but you are still stuck in the exact same error loop, do this:

Go to your agent's actions in Copilot Studio and completely delete the Custom Connector. The agent must be completely isolated, with zero active plugins or connections.
Open a brand-new browser tab (or Incognito mode) and trigger a New test session.
Ask the bot a basic, generic question out of context (e.g., a simple "Hello").

The Finding: If the bot still replies with Error Code: SystemError despite being completely empty, you have confirmed that this specific agent environment is corrupted.
The Solution: Do not waste any more time tweaking the connector. Create a fresh test agent from scratch, verify that it answers "Hello" normally, and then link your Custom Connector with the Policy injection. It will work flawlessly right away!

Happy building! 🚀