docs: clarify MCP discovery and HTTP/2 troubleshooting (#26145)

The MCP guide incorrectly describes private OAuth metadata discovery as
blocked. Document its warning behavior and link to an HTTP/2
stream-stall workaround in troubleshooting.

@netlify /ai/sandboxes/mcp-gateway/

Generated by Codex

---------

Co-authored-by: Codex <noreply@openai.com>

content/manuals/ai/sandboxes/mcp-gateway.md

@@ -87,12 +87,14 @@ If a `--url` hostname resolves to a private, loopback, link-local, or cloud
 metadata address, `sbx` registers the server but warns you about the resolved
 address. Register only URLs you trust. Fetching a manifest from an untrusted
 URL can expose internal services or cloud metadata, and DNS rebinding can
-redirect a hostname after it has been checked. OAuth metadata discovery also
-blocks private and other disallowed addresses, including redirect destinations.
+redirect a hostname after it has been checked.
+
+OAuth metadata discovery also warns and continues when it encounters these
+addresses, including redirect destinations.
 For a trusted internal server, pass `--skip-ssrf-check` to skip both the MCP
-URL check and the OAuth metadata discovery checks. This permits private OAuth
-metadata endpoints and redirects. Use the flag only when you trust the MCP
-host, OAuth provider, and all metadata redirect destinations.
+URL check and the OAuth metadata discovery checks and suppress their warnings.
+Use the flag only when you trust the MCP host, OAuth provider, and all metadata
+redirect destinations.
 
 ### Remote endpoint URL
 
@@ -103,6 +105,9 @@ $ sbx mcp add notion --url https://mcp.notion.com/mcp
 $ sbx mcp add linear --url https://mcp.linear.app/mcp
 ```
 
+If requests to a remote server stall, see
+[MCP server streams stall](troubleshooting.md#mcp-server-streams-stall).
+
 #### Custom request headers
 
 Use `--header 'Name: value'` to send custom HTTP headers to a remote MCP
@@ -343,9 +348,10 @@ against the authorization server's advertised scopes and the resource's
 required scopes. If either source publishes scopes, a scope present in neither
 produces a warning but is still requested. The authorization server can still
 refuse an advertised scope for a particular
-client. For a local authorization flow, `sbx` lists the requested, advertised,
-and refused scopes and suggests a retry command. If the server identifies the
-refused scopes, the command removes them. Otherwise, it uses `--no-scope`.
+client. For a local authorization flow that requested scopes, `sbx` lists the
+requested, advertised, and refused scopes and suggests a retry command. If the
+server identifies the refused scopes, the command removes them. Otherwise, it
+uses `--no-scope`.
 `sbx` never retries automatically.
 
 For each OAuth-backed remote server exposed to a sandbox, the gateway exposes a

content/manuals/ai/sandboxes/troubleshooting.md

@@ -196,6 +196,20 @@ configured to use the forward proxy. See
 [Monitoring network activity](governance/monitor-and-enforce/monitoring.md)
 for details.
 
+## MCP server streams stall
+
+If a remote MCP server's HTTP/2 handling stalls long-lived streams, register
+it with `--disable-http2` to use HTTP/1.1:
+
+```console
+$ sbx mcp add acme --url https://mcp.acme.com/mcp --disable-http2
+```
+
+Replace the example URL with your MCP endpoint. The setting applies to later
+connections to this server. The flag requires `--url` and can't be used with
+`--command` or `--local`. For registration options, see
+[Register an MCP server](mcp-gateway.md#register-an-mcp-server).
+
 ## API calls fail with a certificate error
 
 If your organization uses a proxy that inspects HTTPS traffic, agent requests