Feature Discussion: gateway compatibility for Power Platform / Copilot Studio

[zlucas-netapp]

Deploying ONTAP MCP behind Power Platform On-Premises Data Gateway for Copilot Studio

Preface

This is in relation to issue #119 where the stateless mode did help but did not solve the full integration issue with CoPilot Studio. I ended up recreating the environment locally in our lab, forking the current repo and working through this problem with GitHub Copilot - by no means am I an experienced developer and unsure if the proposed fixes our to invasive on the larger codebase. However, this does work and allowed me to give an agent in CoPilot Studio access to my on-prem MCP. I would like guidance around potentially implementing this and raising an issue for the correct integration to make this a reality for all users. All discussion and feedback is welcome. Below is CoPilots summary of the issues and what was done to resolve.

Scenario

I'm connecting ONTAP MCP to Microsoft Copilot Studio via the Power Platform on-premises data gateway. The goal is to let a Copilot Studio agent use ONTAP MCP tools natively through a custom connector, without exposing the MCP server to the internet.

Architecture:

Copilot Studio Agent → Power Platform Cloud → On-Premises Data Gateway  → ONTAP MCP Server 

The custom connector is created from a Swagger 2.0 spec with x-ms-agentic-protocol: mcp-streamable-1.0 — this tells Copilot Studio to treat the endpoint as a native MCP server and handle tool discovery/invocation automatically.

---

Custom Connector Swagger Spec

This is the full spec imported into Power Platform as a custom connector:

swagger: '2.0'
info:
  title: NetApp ONTAP MCP
  description: MCP connector for NetApp ONTAP storage management via Streamable HTTP transport for Copilot Studio and Power Automate.
  version: 1.0.0
host: <MY_IP>
basePath: /
schemes:
  - http
consumes:
  - application/json
produces:
  - application/json
  - text/event-stream
securityDefinitions:
  api_key:
    type: apiKey
    in: header
    name: X-API-Key
security:
  - api_key: []
paths:
  /mcp:
    post:
      summary: NetApp ONTAP MCP Server
      description: Streamable HTTP MCP endpoint. Tools are discovered at runtime by the MCP client.
      x-ms-agentic-protocol: mcp-streamable-1.0
      operationId: InvokeMCP
      parameters:
        - name: Content-Type
          in: header
          type: string
          required: true
          default: application/json
          x-ms-visibility: internal
        - name: Accept
          in: header
          type: string
          required: true
          default: "application/json, text/event-stream"
          x-ms-visibility: internal
      responses:
        '200':
          description: Success

Key points:

• x-ms-agentic-protocol: mcp-streamable-1.0 is what makes Copilot Studio treat this as an MCP endpoint
• x-ms-visibility: internal hides the header params from the agent — they're sent automatically
• The connector is bound to the on-premises data gateway in the Power Platform connection settings

---

Errors Encountered

Error 1: Generic gateway failure (SSE incompatibility)

With the stock ONTAP MCP server, every request from Copilot Studio returned:

"An error occurred while sending the request."

No logs appeared on the MCP server at all — the gateway rejected the response before forwarding it. The root cause: ONTAP MCP responds with Content-Type: text/event-stream and Transfer-Encoding: chunked. The on-premises data gateway does not support relaying SSE/chunked streams. It expects a complete response body with Content-Type: application/json.

Error 2: HTTP 415 — Content-Type validation failure

After enabling --json-response (which makes the server return JSON instead of SSE), requests started reaching the server but were rejected with:

POST {"jsonrpc":"2.0","id":"1","method":"initialize","params":{"capabilities":{},"clientInfo":{"agentAuthenticationMode":"Integrated","agentName":"Agent","name":"mcs","version":"1.0.0"},"protocolVersion":"2024-11-05","sessionContext":{}}}
Response: status=415, body=
Content-Type must be 'application/json'

The --inspect-traffic flag confirmed the JSON-RPC body arrived intact, but the Go MCP SDK rejected the request at this validation point in streamable.go:

if req.Method == http.MethodPost && baseMediaType(req.Header.Get("Content-Type")) != "application/json" {
    http.Error(w, "Content-Type must be 'application/json'", http.StatusUnsupportedMediaType)
    return
}

baseMediaType() uses Go's mime.ParseMediaType(). The gateway sends something that string-compares as "application/json" but fails mime.ParseMediaType() — likely a BOM, trailing whitespace, or non-standard charset parameter. The body is fine; only the header is broken.

---

Code Changes That Fixed It

Change 1: --json-response CLI flag

Wires the existing StreamableHTTPOptions.JSONResponse SDK field to a CLI flag so the server returns application/json responses instead of text/event-stream. This is already MCP spec-compliant per §2.1.5.

cmd/cmds.go — added field to StartCmd:

type StartCmd struct {
    Host           string `default:"localhost" help:"Listening address"`
    Port           int    `default:"8080" help:"Listening port" env:"ONTAP_MCP_PORT"`
    InspectTraffic bool   `default:"false" help:"Inspect MCP HTTP traffic"`
    ReadOnly       bool   `default:"false" help:"Run MCP in read-only mode."`
    Stateless      bool   `default:"false" help:"Run in stateless mode (no mcp-session-id header validation)."`
    JSONResponse   bool   `default:"false" help:"Respond with application/json instead of text/event-stream. Required when deploying behind proxies or gateways that do not relay SSE/chunked responses, e.g. Power Platform on-premises data gateway."`
}

server/server.go — added to Options struct and wired to StreamableHTTPOptions:

type Options struct {
    Host           string
    InspectTraffic bool
    Port           int
    ReadOnly       bool
    Stateless      bool
    JSONResponse   bool
}

handler = mcp.NewStreamableHTTPHandler(func(*http.Request) *mcp.Server {
    return server
}, &mcp.StreamableHTTPOptions{Stateless: a.options.Stateless, JSONResponse: a.options.JSONResponse})

This fixed Error 1 — the gateway could now relay the complete JSON response body.

---

Change 2: Header normalization middleware

Added to the existing wrappedHandler in server/server.go, positioned before the SDK handler receives the request:

wrappedHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    if r.URL.Path == "/health" {
        http.DefaultServeMux.ServeHTTP(w, r)
        return
    }

    w.Header().Set("Access-Control-Allow-Origin", "*")
    w.Header().Set("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
    w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Mcp-Protocol-Version, Mcp-Session-Id")

    if r.Method == http.MethodOptions {
        w.WriteHeader(http.StatusOK)
        return
    }

    // Force correct headers for gateway compatibility.
    // The on-premises data gateway sends subtly malformed values that
    // fail mime.ParseMediaType validation in the MCP SDK.
    if r.Method == http.MethodPost {
        r.Header.Set("Content-Type", "application/json")
        r.Header.Set("Accept", "application/json, text/event-stream")
    }

    handler.ServeHTTP(w, r)
})

This unconditionally overwrites both headers on every POST before the SDK validates them. The body is untouched — only the metadata is normalized.

This fixed Error 2 — the SDK no longer rejects gateway requests.

---

Final Deployment

ontap-mcp start \
  --host 0.0.0.0 --port 8083 \
  --stateless \
  --json-response \
  --read-only \
  --config /opt/mcp/ontap.yaml

Flag	Purpose
--stateless	Already existed. Gateway doesn't preserve Mcp-Session-Id headers between requests.
--json-response	New. Returns JSON body instead of SSE stream.
--read-only	Already existed. Reduces tool count to stay under Copilot Studio's 70-tool limit.

Result

Copilot Studio agent successfully:

• Discovers ONTAP MCP tools via initialize → tools/list
• Invokes tools (list_registered_clusters, ontap_get, search_ontap_endpoints, etc.)
• Receives JSON-RPC responses through the gateway
• Queries all 4 registered ONTAP clusters

Questions for the Team

1. Would a PR adding the --json-response flag be welcome? It's a minimal change (wires an existing SDK field) and enables any deployment behind a non-SSE-compatible proxy.

2. Header normalization approach: My implementation is unconditional (always rewrites). A cleaner upstream version might be a --gateway-compat flag that opts into lenient header handling. Thoughts on the right pattern?

3. Tool count filtering: Copilot Studio caps at 70 tools. ONTAP MCP registers ~72 with catalog tools. Would a --tags or --include-tools flag for selective tool registration be useful?

[cgrinds]

hi @zlucas-netapp thanks for the great discussion!

1. A PR for (1) would be great and makes sense.

2. I believe (2) is already fixed upstream at mcp: remove default cross origin protection modelcontextprotocol/go-sdk#906. Can you update your go.mod to use github.com/modelcontextprotocol/go-sdk v1.6.0-pre.1 and see if that fixes your issue? I'd rather wait for the upstream fix instead of duplicating it in our code.

3. I wish there was broader support for tool search. Until tool search is more broadly available, something like an include-tools flag might be helpful. Were you thinking that include-tools would be a regex that is used to select which tools are registered at startup? A custom agent might be another way to handle this.

[zlucas-netapp]

This was spot on. Thanks @cgrinds!

I removed the middleware layer and updated the go.mod and the connector checked out!

I will raise an issue on number 1 and is there a timeline on when that pre-release will be in ONTAP MCP? Want to make sure I have this documentation for correct for the customer I am working with.

[cgrinds]

In regards to timeline - when do you need this? We don't generally pull in pre-release dependency, but in this case, ontap-mcp CI passes all tool tests when running with v1.6.0-pre.1 so the risk seems low.

[zlucas-netapp]

The sooner the better, we have a customer trying to integrate this currently. They are waiting on the fix to be able to use this.

[cgrinds]

@zlucas-netapp ontap-mcp now includes 1.6.0-pre.1 per #129

[musaabhasan]

For this connector path, I would document the security and operability assumptions very explicitly because the architecture crosses several trust zones.

The flow is effectively:

Copilot Studio -> Power Platform cloud -> on-premises data gateway -> ONTAP MCP server -> storage management APIs

A few controls seem worth making first-class in the guidance:

• the gateway should be the only network path to the MCP server,
• MCP tools exposed through the connector should be scoped to the smallest useful ONTAP operations,
• high-impact storage actions should require a separate approval or be excluded from the initial connector profile,
• logs should correlate Copilot user/session, gateway request, MCP tool, ONTAP API call, and result,
• secrets should stay in the gateway or connector credential store, not in prompts or tool arguments,
• and the Swagger/custom connector should be versioned so tool-surface changes are reviewable.

An include-tools control sounds useful, but I would prefer an allowlist over a broad regex for production guidance. Regex selection is flexible, but it can accidentally include a newly added high-impact tool. A named allowlist with a documented review step is safer for storage administration.

The integration also seems like a good candidate for a minimal "safe profile" example: read/list tools first, then a separate expanded profile for controlled write/admin tools.