[github-actions]

agentgateway/agentgateway#4160 — mcp: validate duplicate target names

Docs versions: standalone/main, standalone/latest, kubernetes/main, kubernetes/latest (first shipped in v1.7.0)

What changes for users: Standalone MCP target lists now reject duplicate name values with duplicate mcp target name "<name>". Kubernetes service selectors now resolve duplicate generated MCP target names deterministically: static targets win over selected Services, and selected Service ties are broken by namespace, annotation use, creation time, and name.

What the docs now say: The standalone MCP configuration modes page now says that mcp.targets and routes[].backends[].mcp.targets names must be unique. The Kubernetes Virtual MCP page now explains how selector target-name collisions are resolved.

Not verified: Configuration was not applied or run, and internal links are unchecked.

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

• Code PR: mcp: validate duplicate target names agentgateway#4160
• Code issue: none linked
• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main, standalone/latest, kubernetes/main, kubernetes/latest; first shipped in v1.7.0
• Category: scoped-edit / pr

Plan, and what changed it

• Planned: Document duplicate MCP target-name behavior on the MCP pages that already explain multiplexed targets.
• Learned: neighbors/README.md showed nearby changes in crates/agentgateway/src/types/local.rs, but those changes cover environment-variable expansion and Gateway API defaults, not MCP target-name validation.
• Did: Updated the standalone MCP configuration modes pages for main and latest, and added gated Kubernetes selector collision behavior to the shared Virtual MCP asset.

Why a documentation change is necessary

The pull request adds standalone validation that rejects duplicate MCP target names, and configuration-modes.md already explains where readers configure MCP targets. The pull request also changes Kubernetes selector translation to ignore lower-priority Services when generated target names collide, and multiplex.md already teaches selector-based virtual MCP backends. Without this update, readers can create duplicate target names without knowing whether validation fails or which selected Service is used.

I left assets/agw-docs/pages/agentgateway/mcp/static.md unchanged because that page covers fixed static and backendRef targets, not selector-generated target names.

What changed on disk

• assets/agw-docs/pages/agentgateway/mcp/multiplex.md — Added a v1.7+ note about selector target-name collisions and the precedence order for the retained target.
• content/docs/standalone/latest/documentation/mcp/configuration-modes.md — Added standalone duplicate target-name validation behavior.
• content/docs/standalone/main/documentation/mcp/configuration-modes.md — Added the same standalone duplicate target-name validation behavior for main.

How to verify this change

1. Create a standalone config with two entries under mcp.targets that use the same name, and run agentgateway --validate-only -f config.yaml. The command exits nonzero and reports duplicate mcp target name "<name>".
2. In Kubernetes mode, create an AgentgatewayBackend with a static target named trusted and a selector that matches a Service annotated with agentgateway.dev/mcp-target-name: trusted.
3. Check the backend status message or configuration warning. It contains MCP target "trusted" from Service <namespace>/<name> conflicts with static target; ignored, and the generated backend keeps the static trusted target.

What was not verified

• The configuration was not applied to a cluster or run with a standalone binary, so every command and behavior check is unrun.
• Internal links are unchecked because Hugo was not run.

How the pages were chosen (triage report)

Draft a documentation change

agentgateway/agentgateway#4160 — mcp: validate duplicate target names

• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main, standalone/latest, kubernetes/main, kubernetes/latest
• Summary (the title; the body has no description): mcp: validate duplicate target names
• Not tested: no cluster was available, so every command in this diff is unrun

Release notes

This pull request also adds its release-note entries:

• content/docs/standalone/latest/release-notes/release-notes.md: mcp: validate duplicate target names (fix, under MCP)
• content/docs/standalone/main/release-notes/release-notes.md: mcp: validate duplicate target names (fix, under MCP)

Release notes kept out of a tree. Check that each change really does not reach the trees named here:

• mcp: validate duplicate target names agentgateway#4160: not placed for kubernetes/main, kubernetes/latest, because the draft edited no page there. If the change also reaches that tree, add the note there.

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

[cloudflare-workers-and-pages]

Deploying agentproxy with    Cloudflare Pages

Latest commit:	948cead
Status:	✅  Deploy successful!
Preview URL:	https://47faabc1.agentproxy.pages.dev
Branch Preview URL:	https://pr-tracker-draft-agentgatewa-0l98.agentproxy.pages.dev

View logs

[kristin-kronstain-brown]

Moved this PR's release-notes entry to the combined release-notes PR, #1482, so the draft PRs stop conflicting on the release-notes pages. Review or change the entry there.