[Automated] Draft docs (agentgateway): fix(mcp): harden OpenAPI path parameter handling

[github-actions]

Draft a documentation change

agentgateway/agentgateway#3598 — fix(mcp): harden OpenAPI path parameter handling

• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main, kubernetes/main
• Summary (read from the body): Validate and safely encode path parameter values before forwarding requests.
• Tested: a cluster was available — a cluster is provisioned in the drafting job for agentgateway/upstream at kubernetes/main

agentgateway/agentgateway#3598 - fix(mcp): harden OpenAPI path parameter handling

• Product: agentgateway (upstream) -> agentgateway/website
• Docs version: standalone/main and kubernetes/main

agentgateway/agentgateway#3598 hardens OpenAPI path parameter handling for MCP tools generated from an OpenAPI schema. Readers configuring OpenAPI MCP servers now know that path parameters are required, that values must be strings or numbers, and that string values are percent-encoded before forwarding. The behavior changes existing invalid inputs: missing values, unsupported value types, empty segments, and . or .. path segments now fail before any upstream HTTP request is sent. Before this change, an invalid value could leave a literal template placeholder in the path or forward a traversal-like value.

How agentgateway-3598 was drafted, and what was not verified

agentgateway/agentgateway#3598 - fix(mcp): harden OpenAPI path parameter handling

• Code PR: fix(mcp): harden OpenAPI path parameter handling agentgateway#3598
• Code issue: none linked
• Product: agentgateway (upstream) -> agentgateway/website
• Docs version: standalone/main and kubernetes/main
• Category: scoped-edit / pr

Plan, and what changed it

• Planned: Document the OpenAPI path parameter validation behavior on the OpenAPI MCP server pages for the resolved standalone/main and kubernetes/main trees.
• Learned: content/docs/kubernetes/main/integrations/mcp/servers.md is a redirect, the Kubernetes MCP candidates are section indexes or generic MCP pages, and no Kubernetes OpenAPI server guide exists in the target set.
• Did: Added a Path parameters section to content/docs/standalone/main/integrations/mcp/servers/openapi.md; wrote no Kubernetes prose because the available pages do not own OpenAPI server behavior.

Why a documentation change is necessary

The pull request changes how OpenAPI MCP tools handle path parameters. The existing standalone OpenAPI page shows an inline OpenAPI schema with a path parameter, but it did not explain that path parameters are forced into the required tool schema or which values are rejected before forwarding. A reader using generated tools against an OpenAPI backend would not know why missing, boolean, empty, or dot-segment path values now fail locally instead of reaching the upstream API.

What changed on disk

• content/docs/standalone/main/integrations/mcp/servers/openapi.md - Added the required path-parameter behavior, accepted value types, percent-encoding behavior, and invalid-request cases.
• No Kubernetes files written: no target page in the Kubernetes tree documents OpenAPI MCP servers, and the section indexes and redirect are not valid homes for this behavior-specific guidance.

How to verify this change

1. Follow the standalone OpenAPI server guide to start the Petstore server and run agentgateway -f config.yaml.

2. Open a session against the local MCP endpoint and call the generated getPetById tool with an unsafe path parameter value.

   SID=$(curl -sS -D - -o /dev/null --max-time 30 -X POST http://localhost:3000/mcp \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json, text/event-stream' \
     -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"verify","version":"1.0"}},"id":1}' \
     | awk 'tolower($1)=="mcp-session-id:" {gsub("\r","",$2); print $2}')
   
   curl -sS --max-time 30 -X POST http://localhost:3000/mcp \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json, text/event-stream' \
     -H "Mcp-Session-Id: $SID" \
     -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"getPetById","arguments":{"path":{"petId":"../admin"}}},"id":2}'

3. The response shows an invalid request error for the petId path parameter, and the Petstore container logs do not show a request for ../admin, %2Fadmin, or a literal {petId} path.

Proposed release note

The proposed note does not link to the docs page because the item resolved to both standalone/main and kubernetes/main, but only the standalone tree has an OpenAPI MCP server page.

What was not verified

The configuration was not applied to a cluster, so every command in this diff is unrun. The workflow-provided cluster-facts.md file was used only as API surface; no Kubernetes resources were applied. The standalone OpenAPI guide was not run locally in this CI sandbox.

A declared version this draft does not reach

This pull request is planned for more than one documentation version,
and nothing in the diff publishes to:

• kubernetes/main

A file under assets/ reaches a version tree only where a page in that
tree reuses it, so editing a shared asset does not by itself cover every
mode a product ships. Either that version still needs writing, or the
change genuinely does not apply there and the reason belongs in this body.

Draft branch: pr-tracker-draft-agentgateway-3598

---

Important

The test suite has not run on this pull request. It was opened by github-actions[bot], and GitHub does not start workflows for pull requests opened with the repository's own token. Doc tests, link checking and the static checks are held as action_required until somebody presses Approve and run on the Checks tab. Cloudflare Pages and DCO are GitHub Apps rather than Actions, so those two do run on their own.

Please approve the checks before reviewing the content: an absence of failures here means the tests have not run, not that they passed.

[cloudflare-workers-and-pages]

Deploying agentproxy with    Cloudflare Pages

Latest commit:	7633855
Status:	✅  Deploy successful!
Preview URL:	https://7a08635e.agentproxy.pages.dev
Branch Preview URL:	https://pr-tracker-draft-agentgatewa-t939.agentproxy.pages.dev

View logs