Merge branch 'DOC-1867-Document-feature-AI-Gateway-help-cloud-team-polish-clean-up' into adp-pkg1

# Conflicts:
#	modules/ai-agents/pages/mcp/remote/tool-patterns.adoc

Author: paulohtb6

modules/ROOT/nav.adoc

@@ -64,39 +64,35 @@
 *** xref:ai-agents:observability/ingest-custom-traces.adoc[Ingest Traces from Custom Agents]
 ** xref:ai-agents:ai-gateway/index.adoc[AI Gateway]
 *** xref:ai-agents:ai-gateway/what-is-ai-gateway.adoc[Overview]
-*** xref:ai-agents:ai-gateway/gateway-modes.adoc[Gateway Modes]
 *** xref:ai-agents:ai-gateway/gateway-quickstart.adoc[Quickstart]
 *** xref:ai-agents:ai-gateway/gateway-architecture.adoc[Architecture]
 *** For Administrators
 **** xref:ai-agents:ai-gateway/admin/setup-guide.adoc[Setup Guide]
-**** xref:ai-agents:ai-gateway/admin/configure-ai-hub.adoc[Configure AI Hub Gateway]
-**** xref:ai-agents:ai-gateway/admin/eject-to-custom-mode.adoc[Eject to Custom Mode]
 *** For Builders
 **** xref:ai-agents:ai-gateway/builders/discover-gateways.adoc[Discover Gateways]
-**** xref:ai-agents:ai-gateway/builders/use-ai-hub-gateway.adoc[Use AI Hub Gateway]
 **** xref:ai-agents:ai-gateway/builders/connect-your-agent.adoc[Connect Your Agent]
 **** xref:ai-agents:ai-gateway/cel-routing-cookbook.adoc[CEL Routing Patterns]
 **** xref:ai-agents:ai-gateway/mcp-aggregation-guide.adoc[MCP Aggregation]
 //*** Observability
 //**** xref:ai-agents:ai-gateway/observability-logs.adoc[Request Logs]
 //**** xref:ai-agents:ai-gateway/observability-metrics.adoc[Metrics and Analytics]
 //*** xref:ai-agents:ai-gateway/migration-guide.adoc[Migrate]
-*** xref:ai-agents:ai-gateway/integrations/index.adoc[Integrations]
-**** Claude Code
-***** xref:ai-agents:ai-gateway/integrations/claude-code-admin.adoc[Admin Guide]
-***** xref:ai-agents:ai-gateway/integrations/claude-code-user.adoc[User Guide]
-**** Cline
-***** xref:ai-agents:ai-gateway/integrations/cline-admin.adoc[Admin Guide]
-***** xref:ai-agents:ai-gateway/integrations/cline-user.adoc[User Guide]
-**** Continue.dev
-***** xref:ai-agents:ai-gateway/integrations/continue-admin.adoc[Admin Guide]
-***** xref:ai-agents:ai-gateway/integrations/continue-user.adoc[User Guide]
-**** Cursor IDE
-***** xref:ai-agents:ai-gateway/integrations/cursor-admin.adoc[Admin Guide]
-***** xref:ai-agents:ai-gateway/integrations/cursor-user.adoc[User Guide]
-**** GitHub Copilot
-***** xref:ai-agents:ai-gateway/integrations/github-copilot-admin.adoc[Admin Guide]
-***** xref:ai-agents:ai-gateway/integrations/github-copilot-user.adoc[User Guide]
+//*** xref:ai-agents:ai-gateway/integrations/index.adoc[Integrations]
+//**** Claude Code
+//***** xref:ai-agents:ai-gateway/integrations/claude-code-admin.adoc[Admin Guide]
+//***** xref:ai-agents:ai-gateway/integrations/claude-code-user.adoc[User Guide]
+//**** Cline
+//***** xref:ai-agents:ai-gateway/integrations/cline-admin.adoc[Admin Guide]
+//***** xref:ai-agents:ai-gateway/integrations/cline-user.adoc[User Guide]
+//**** Continue.dev
+//***** xref:ai-agents:ai-gateway/integrations/continue-admin.adoc[Admin Guide]
+//***** xref:ai-agents:ai-gateway/integrations/continue-user.adoc[User Guide]
+//**** Cursor IDE
+//***** xref:ai-agents:ai-gateway/integrations/cursor-admin.adoc[Admin Guide]
+//***** xref:ai-agents:ai-gateway/integrations/cursor-user.adoc[User Guide]
+//**** GitHub Copilot
+//***** xref:ai-agents:ai-gateway/integrations/github-copilot-admin.adoc[Admin Guide]
+//***** xref:ai-agents:ai-gateway/integrations/github-copilot-user.adoc[User Guide]
 
 * xref:develop:connect/about.adoc[Redpanda Connect]
 ** xref:develop:connect/connect-quickstart.adoc[Quickstart]

modules/ai-agents/pages/ai-gateway/admin/setup-guide.adoc

@@ -8,7 +8,7 @@
 
 include::ai-agents:partial$ai-gateway-byoc-note.adoc[]
 
-This guide walks administrators through the complete setup process for AI Gateway, from enabling LLM providers to configuring routing policies and MCP tool aggregation.
+This guide walks administrators through the setup process for AI Gateway, from enabling LLM providers to configuring routing policies and MCP tool aggregation.
 
 After completing this guide, you will be able to:
 
@@ -26,7 +26,7 @@ After completing this guide, you will be able to:
 
 Providers represent upstream services (Anthropic, OpenAI, Google AI) and associated credentials. Providers are disabled by default and must be enabled explicitly by an administrator.
 
-. In the Redpanda Cloud Console, navigate to *AI Gateway* → *Providers*.
+. In the Redpanda Cloud Console, navigate to *Agentic AI* → *Providers*.
 . Select a provider (for example, Anthropic).
 . On the Configuration tab for the provider, click *Add configuration*.
 . Enter your API Key for the provider.
@@ -43,17 +43,15 @@ The model catalog is the set of models made available through the gateway. Model
 
 The infrastructure that serves the model differs based on the provider you select. For example, OpenAI has different reliability and availability metrics than Anthropic. When you consider all metrics, you can design your gateway to use different providers for different use cases.
 
-. Navigate to *AI Gateway* → *Models*.
+. Navigate to *Agentic AI* → *Models*.
 . Review the list of available models from enabled providers.
-. For each model you want to expose through gateways, toggle it to *Enabled*.
-+
-Common models to enable:
+. For each model you want to expose through gateways, toggle it to *Enabled*. For example:
 +
 --
-* `openai/gpt-4o` - OpenAI's most capable model
-* `openai/gpt-4o-mini` - Cost-effective OpenAI model
-* `anthropic/claude-sonnet-3.5` - Balanced Anthropic model
-* `anthropic/claude-opus-4` - Anthropic's most capable model
+* `openai/gpt-5.2`
+* `openai/gpt-5.2-mini`
+* `anthropic/claude-sonnet-4.5`
+* `anthropic/claude-opus-4.6`
 --
 
 . Click *Save changes*.
@@ -62,14 +60,13 @@ Only enabled models will be accessible through gateways. You can enable or disab
 
 === Model naming convention
 
-Model requests must use the `vendor/model_id` format in the model property of the request body. This format allows AI Gateway to route requests to the appropriate provider.
-
-Examples:
+Model requests must use the `vendor/model_id` format in the model property of the request body. This format allows AI Gateway to route requests to the appropriate provider. For example:
 
-* `openai/gpt-4o`
-* `anthropic/claude-sonnet-3.5`
-* `openai/gpt-4o-mini`
+* `openai/gpt-5.2`
+* `anthropic/claude-sonnet-4.5`
+* `openai/gpt-5.2-mini`
 
+ifdef::ai-hub-available[]
 == Choose a gateway mode
 
 Before creating a gateway, decide which mode fits your needs.
@@ -102,12 +99,13 @@ For detailed comparison, see xref:ai-gateway/gateway-modes.adoc[].
 
 * *AI Hub Mode*: See xref:ai-gateway/admin/configure-ai-hub.adoc[] for setup instructions
 * *Custom Mode*: Continue with "Create a gateway" below for manual configuration
+endif::[]
 
 == Create a gateway
 
 A gateway is a logical configuration boundary (policies + routing + observability) on top of a single deployment. It's a "virtual gateway" that you can create per team, environment (staging/production), product, or customer.
 
-. Navigate to *AI Gateway* → *Gateways*.
+. Navigate to *Agentic AI* → *Gateways*.
 . Click *Create Gateway*.
 . Configure the gateway:
 +
@@ -126,11 +124,12 @@ TIP: A workspace is conceptually similar to a resource group in Redpanda streami
 . After creation, note the following information:
 +
 --
-* *Gateway ID*: Unique identifier (for example, `gw_abc123`) - users include this in the `rp-aigw-id` header
-* *Gateway Endpoint*: Base URL for API requests (for example, `https://gw.ai.panda.com`)
+* *Gateway endpoint*: URL for API requests (for example, `https://example/gateways/d633lffcc16s73ct95mg/v1`) 
++
+The gateway ID is embedded in the URL.
 --
 
-You'll share the Gateway ID and Endpoint with users who need to access this gateway.
+You'll share the gateway endpoint with users who need to access this gateway.
 
 == Configure LLM routing
 
@@ -188,7 +187,7 @@ Provider pools define which LLM providers handle requests, with support for prim
 --
 * *Name*: For example, `primary-anthropic`
 * *Providers*: Select one or more providers (for example, Anthropic)
-* *Models*: Choose which models to include (for example, `anthropic/claude-sonnet-3.5`)
+* *Models*: Choose which models to include (for example, `anthropic/claude-sonnet-4.5`)
 * *Load balancing*: If multiple providers are selected, choose distribution strategy (round-robin, weighted, etc.)
 --
 
@@ -197,7 +196,7 @@ Provider pools define which LLM providers handle requests, with support for prim
 --
 * *Name*: For example, `fallback-openai`
 * *Providers*: Select fallback provider (for example, OpenAI)
-* *Models*: Choose fallback models (for example, `openai/gpt-4o`)
+* *Models*: Choose fallback models (for example, `openai/gpt-5.2`)
 * *Trigger conditions*: When to activate fallback:
   ** Rate limit exceeded (429 from primary)
   ** Timeout (primary provider slow)
@@ -215,8 +214,8 @@ Example CEL expression for tier-based routing:
 [source,cel]
 ----
 request.headers["x-user-tier"] == "premium"
-  ? "anthropic/claude-opus-4"
-  : "anthropic/claude-sonnet-3.5"
+  ? "anthropic/claude-opus-4.6"
+  : "anthropic/claude-sonnet-4.5"
 ----
 
 . Click *Save routing configuration*.
@@ -227,49 +226,78 @@ TIP: Provider pool (UI) = Backend pool (API)
 
 If a provider pool contains multiple providers, you can distribute traffic to balance load or optimize for cost/performance:
 
-* *Round-robin*: Distribute evenly across all providers
-* *Weighted*: Assign weights (for example, 80% to Anthropic, 20% to OpenAI)
-* *Least latency*: Route to fastest provider based on recent performance
-* *Cost-optimized*: Route to cheapest provider for each model
+* Round-robin: Distribute evenly across all providers
+* Weighted: Assign weights (for example, 80% to Anthropic, 20% to OpenAI)
+* Least latency: Route to fastest provider based on recent performance
+* Cost-optimized: Route to cheapest provider for each model
 
 == Configure MCP tools (optional)
 
 If your users will build glossterm:AI agent[,AI agents] that need access to glossterm:MCP tool[,tools] via glossterm:MCP[,Model Context Protocol (MCP)], configure MCP tool aggregation.
 
 On the gateway details page, select the *MCP* tab to configure tool discovery and execution. The MCP proxy aggregates multiple glossterm:MCP server[,MCP servers], allowing agents to find and call tools through a single endpoint.
 
+=== Configure MCP rate limits
+
+Rate limits for MCP work the same way as LLM rate limits.
+
+. In the *MCP* tab, locate the *Rate Limit* section.
+. Click *Add rate limit*.
+. Configure the maximum requests per second and optional burst allowance.
+. Click *Save*.
+
 === Add MCP servers
 
-. In the *MCP* tab, click *Add MCP server*.
+. In the *MCP* tab, click *Create MCP Server*.
 . Configure the server:
 +
 --
-* *Server name*: Human-readable identifier (for example, `database-server`, `slack-server`)
-* *Server URL*: Endpoint for the MCP server (for example, `https://mcp-database.example.com`)
-* *Authentication*: Configure authentication if required (bearer token, API key, mTLS)
-* *Enabled tools*: Select which tools from this server to expose (or *All tools*)
+* *Server ID*: Unique identifier for this server
+* *Display Name*: Human-readable name (for example, `database-server`, `slack-server`)
+* *Server Address*: Endpoint URL for the MCP server (for example, `https://mcp-database.example.com`)
 --
 
-. Click *Test connection* to verify connectivity.
-. Click *Save* to add the server to this gateway.
+. Configure server settings:
++
+--
+* *Timeout (seconds)*: Maximum time to wait for a response from this server
+* *Enabled*: Whether this server is active and accepting requests
+* *Defer Loading Override*: Controls whether tools from this server are loaded upfront or on demand
++
+[cols="1,2"]
+|===
+|Option |Description
 
-Repeat for each MCP server you want to aggregate.
+|Inherit from gateway
+|Use the gateway-level deferred loading setting (default)
 
-=== Configure deferred tool loading
+|Enabled
+|Always defer loading from this server. Agents receive only a search tool initially and query for specific tools when needed. This can reduce token usage by 80-90%.
 
-Deferred tool loading dramatically reduces token costs by initially exposing only a search tool and orchestrator, rather than listing all available tools.
+|Disabled
+|Always load all tools from this server upfront.
+|===
 
-. In the *MCP* tab, locate *Deferred Loading*.
-. Toggle *Enable deferred tool loading* to *On*.
-. Configure behavior:
+* *Forward OIDC Token Override*: Controls whether the client's OIDC token is forwarded to this MCP server
 +
---
-* *Initially expose*: Search tool + orchestrator only
-* *Load on demand*: Tools are retrieved when agents query for them
-* *Token savings*: Expect 80-90% reduction in token usage for tool definitions
+[cols="1,2"]
+|===
+|Option |Description
+
+|Inherit from gateway
+|Use the gateway-level OIDC forwarding setting (default)
+
+|Enabled
+|Always forward the OIDC token to this server
+
+|Disabled
+|Never forward the OIDC token to this server
+|===
 --
 
-. Click *Save*.
+. Click *Save* to add the server to this gateway.
+
+Repeat for each MCP server you want to aggregate.
 
 See xref:ai-gateway/mcp-aggregation-guide.adoc[] for detailed information about MCP aggregation.
 
@@ -279,11 +307,24 @@ The MCP orchestrator is a built-in MCP server that enables programmatic tool cal
 
 Example: A workflow requiring 47 file reads can be reduced from 49 round trips to just 1 round trip using the orchestrator.
 
-The orchestrator is enabled by default when you enable MCP tools. You can configure:
+The orchestrator is pre-configured when you initialize the MCP gateway. Its server configuration (Server ID, Display Name, Transport, Command, and Timeout) is system-managed and cannot be modified.
 
-* *Execution timeout*: Maximum time for orchestrator workflows (for example, 30 seconds)
-* *Memory limit*: Maximum memory for JavaScript execution (for example, 128MB)
-* *Allowed operations*: Restrict which MCP tools can be called from orchestrator workflows
+You can configure blocked tool patterns to prevent specific tools from being called through the orchestrator:
+
+. In the *MCP* tab, select the orchestrator server to edit it.
+. Under *Blocked Tools*, click *Add Pattern* to add glob patterns for tools that should be blocked from execution.
++
+Example patterns:
++
+--
+* `server_id:*` - Block all tools from a specific server
+* `*:dangerous_tool` - Block a specific tool across all servers
+* `specific:tool` - Block a single tool on a specific server
+--
++
+NOTE: The orchestrator's own tools are blocked by default to prevent recursive execution.
+
+. Click *Save*.
 
 == Verify your setup
 
@@ -293,9 +334,8 @@ After completing the setup, verify that the gateway is working correctly:
 
 [source,bash]
 ----
-curl https://{GATEWAY_ENDPOINT}/v1/models \
-  -H "Authorization: Bearer ${REDPANDA_CLOUD_TOKEN}" \
-  -H "rp-aigw-id: ${GATEWAY_ID}"
+curl ${GATEWAY_ENDPOINT}/models \
+  -H "Authorization: Bearer ${REDPANDA_CLOUD_TOKEN}"
 ----
 
 Expected result: List of enabled models.
@@ -304,37 +344,34 @@ Expected result: List of enabled models.
 
 [source,bash]
 ----
-curl https://{GATEWAY_ENDPOINT}/v1/chat/completions \
+curl ${GATEWAY_ENDPOINT}/chat/completions \
   -H "Authorization: Bearer ${REDPANDA_CLOUD_TOKEN}" \
-  -H "rp-aigw-id: ${GATEWAY_ID}" \
   -H "Content-Type: application/json" \
   -d '{
-    "model": "openai/gpt-4o-mini",
+    "model": "openai/gpt-5.2-mini",
     "messages": [{"role": "user", "content": "Hello, AI Gateway!"}],
     "max_tokens": 50
   }'
 ----
 
 Expected result: Successful completion response.
 
-=== Check observability
+=== Check the gateway overview
 
-. Navigate to *AI Gateway* → *Gateways* → Select your gateway → *Analytics*.
-. Verify that your test request appears in the request logs.
-. Check metrics:
+. Navigate to *Gateways* → Select your gateway → *Overview*.
+. Check the aggregate metrics to verify your test request was processed:
 +
 --
-* Request count: Should show your test request
-* Token usage: Should show tokens consumed
-* Estimated cost: Should show calculated cost
+* Total Requests: Should have incremented
+* Total Tokens: Should show tokens consumed
+* Total Cost: Should show estimated cost
 --
 
 == Share access with users
 
 Now that your gateway is configured, share access with users (builders):
 
-. Provide the *Gateway ID* (for example, `gw_abc123`)
-. Provide the *Gateway Endpoint* (for example, `https://gw.ai.panda.com`)
+. Provide the *Gateway Endpoint* (for example, `https://example/gateways/gw_abc123/v1`)
 . Share API credentials (Redpanda Cloud tokens with appropriate permissions)
 . (Optional) Document available models and any routing policies
 . (Optional) Share rate limits and budget information
@@ -352,6 +389,8 @@ Users can then discover and connect to the gateway using the information provide
 //*Monitor and observe:*
 //
 
+ifdef::integrations-available[]
 *Integrate tools:*
 
 * xref:ai-gateway/integrations/index.adoc[Integrations] - Admin guides for Claude Code, Cursor, and other tools
+endif::[]