docs: Claude Desktop reaches a deployment from Anthropic servers, not locally — stop promising intranet reach on three surfaces

.changeset/mcp-readme-custom-connector-reaches-from-anthropic.md

@@ -0,0 +1,14 @@
+---
+"@objectstack/mcp": patch
+---
+
+docs(mcp): the README no longer promises that Claude Desktop reaches intranet deployments — *Add custom connector* is the claude.ai connector system and dials from Anthropic's servers (#16882)
+
+`packages/mcp/README.md` grouped the clients by **where the client application runs**: "Local clients (Claude Code / Desktop) can reach intranet deployments; claude.ai web connectors additionally need the endpoint publicly reachable." That grouping is wrong for Claude Desktop. Its *Settings → Connectors → Add custom connector* flow is the same claude.ai connector system, and the connection to the MCP server is made **from Anthropic's servers** — Anthropic's custom-connector documentation requires the server to be reachable over the public internet from Anthropic's IP ranges and states that a server on a private corporate network, behind a VPN, or blocked by a firewall will not connect. An operator following the old sentence pointed Claude Desktop at an intranet address and the failure surfaced inside a third-party client, with nothing to connect it back to our instructions.
+
+The README now groups by **where the connection is made from**, which is the mechanism and does not go stale when a client's dialog is redesigned:
+
+- **Claude Code** (`claude mcp add`, or the plugin) dials the endpoint from your own machine, so `localhost` and intranet-only deployments work — this is the door that genuinely reaches a private deployment, and the README now names it as such.
+- **claude.ai (web) and Claude Desktop** go through the one claude.ai custom-connector system and need public HTTPS; a locally trusted certificate does not make a private address reachable.
+
+Documentation only — no exported symbol, endpoint, schema or runtime behaviour changes. The `patch` bump is because `README.md` is in this package's published `files[]`, so the corrected text ships to the npm page.

content/docs/ai/agents.mdx

@@ -83,19 +83,26 @@ Per client:
 | Client | How to connect |
 |---|---|
 | **Claude Code** | `claude mcp add --transport http objectstack https://<your-deployment>/api/v1/mcp` — a browser login opens on first use. Headless alternative: add `--header "x-api-key: osk_..."`. |
-| **Claude Desktop** | Settings → Connectors → *Add custom connector* → paste the MCP URL → sign in when prompted. |
-| **claude.ai (web)** | Settings → Connectors → *Add custom connector* → paste the MCP URL. |
+| **Claude Desktop** | Settings → Connectors → *Add custom connector* → paste the MCP URL → sign in when prompted. Connects from Anthropic's servers — needs public HTTPS (see below). |
+| **claude.ai (web)** | Settings → Connectors → *Add custom connector* → paste the MCP URL. Connects from Anthropic's servers — needs public HTTPS (see below). |
 | **Other MCP clients** | Any client implementing MCP authorization discovers the flow automatically; header-based clients can send the API key instead. |
 
 <Callout type="info">
 **Private / intranet deployments.** OAuth requires HTTPS (localhost is
-exempt, per OAuth 2.1). **Local** clients — Claude Code and Claude Desktop —
-run on your machine, so they can reach an intranet-only deployment (an
-internal CA works). **claude.ai web connectors** connect from Anthropic's
-servers, so they additionally need the MCP endpoint reachable from the public
-internet — a network decision, not a platform switch. On a plain-HTTP
-non-localhost deployment the OAuth track stays dark and the endpoint is
-API-key-only, fail-closed.
+exempt, per OAuth 2.1). What decides reach is **where the connection is made
+from**, not whether the client application runs on your machine. **Claude
+Code** (`claude mcp add`, or the plugin) dials the endpoint from your own
+machine, so it reaches an intranet-only deployment (an internal CA works).
+**claude.ai and Claude Desktop** both go through the same claude.ai
+custom-connector system, which connects **from Anthropic's servers**:
+Anthropic's custom-connector documentation requires the MCP server to be
+reachable over the public internet from Anthropic's IP ranges, and states that
+a server on a private corporate network, behind a VPN, or blocked by a firewall
+will not connect — a locally trusted certificate does not change that. So an
+intranet deployment is connected through the **Claude Code** track; *Add custom
+connector* is not a second door to it — a network fact, not a platform switch.
+On a plain-HTTP non-localhost deployment the OAuth track stays dark and the
+endpoint is API-key-only, fail-closed.
 </Callout>
 
 ## You extend the platform with **skills**, not agents

content/docs/ai/connect-mcp.mdx

@@ -60,6 +60,22 @@ every project.
 (`https://your-deployment.example.com/api/v1/mcp`). The first use walks through
 the same browser login.
 
+<Callout type="warn">
+**This track needs a publicly reachable HTTPS endpoint — it cannot reach
+`localhost` or an intranet address.** *Add custom connector* is the same
+claude.ai connector system in both surfaces, and it connects to your deployment
+**from Anthropic's servers**, not from the machine the client is running on.
+Anthropic's custom-connector documentation requires the MCP server to be
+reachable over the public internet from Anthropic's IP ranges, and states that
+a server on a private corporate network, behind a VPN, or blocked by a firewall
+will not connect. A locally trusted TLS certificate does not make a private
+address reachable, and an `http://` URL is refused before any of that.
+
+For a **local or intranet** deployment, connect through
+[Claude Code](#claude-code-one-command) instead — `claude mcp add` runs on your
+own machine, so `localhost` and intranet addresses work there.
+</Callout>
+
 ## Any MCP client (`.mcp.json`)
 
 Clients that read an `mcpServers` map connect the same way. With an API key:

packages/mcp/README.md

@@ -279,15 +279,28 @@ tool call runs under **your** permissions and row-level security.
 claude mcp add --transport http objectstack https://your-deployment.example.com/api/v1/mcp
 # then approve the browser login on first use
 
-# claude.ai — Settings → Connectors → Add custom connector → paste the MCP URL
-# (requires the deployment to be reachable from the public internet over HTTPS)
-
-# Claude Desktop — Settings → Connectors → Add custom connector
+# claude.ai (web) AND Claude Desktop — Settings → Connectors →
+# Add custom connector → paste the MCP URL. Both drive the same claude.ai
+# connector system, which dials the endpoint FROM Anthropic's servers, so the
+# deployment has to be reachable over public HTTPS.
 ```
 
-TLS is required for OAuth (localhost is exempt, per OAuth 2.1). Local clients
-(Claude Code / Desktop) can reach intranet deployments; claude.ai web
-connectors additionally need the endpoint publicly reachable. Coarse scopes
+TLS is required for OAuth (localhost is exempt, per OAuth 2.1). What decides
+whether a client can reach a deployment is **where the connection is made
+from**, not whether the client application runs on your machine:
+
+- **Claude Code** (`claude mcp add`, or the plugin) dials the endpoint from
+  your own machine, so it reaches `localhost` and intranet-only deployments.
+- **claude.ai (web) and Claude Desktop** both go through the same claude.ai
+  custom-connector system, which connects **from Anthropic's servers**.
+  Anthropic's custom-connector documentation requires the MCP server to be
+  reachable over the public internet from Anthropic's IP ranges, and states
+  that a server on a private corporate network, behind a VPN, or blocked by a
+  firewall will not connect — a locally trusted certificate does not change
+  that.
+
+So a local or intranet deployment is connected through the **Claude Code**
+track; *Add custom connector* is not a second door to it. Coarse scopes
 (`data:read`, `data:write`, `actions:execute`) narrow the exposed tool
 families at consent time; permissions/RLS bind every *object CRUD* call to the
 logged-in user. Business actions are the exception: `actions:execute` gates