From 0f3f9d4fc6bd0e0763f00c0cc0b9fcbca7dd1aea Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 10 Sep 2026 16:30:32 +0000 Subject: [PATCH] docs(mcp): group MCP clients by where the connection is made FROM, not by where the client runs (#16882) `packages/mcp/README.md`, `content/docs/ai/agents.mdx` and `content/docs/ai/connect-mcp.mdx` all told operators that Claude Desktop is a "local client" that reaches intranet deployments. It is not: its *Settings -> Connectors -> Add custom connector* flow is the same claude.ai connector system, and that system dials the MCP server 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 -- so an internal CA does not rescue it either, which `agents.mdx` explicitly promised it would. The three surfaces now split the clients on the mechanism rather than on any dialog's current behaviour, which is what keeps the copy true when a third-party UI is redesigned: * Claude Code (`claude mcp add`, or the plugin) dials from your own machine -> `localhost` and intranet-only deployments work. Named as the door that does work, rather than deleting the promise outright. * claude.ai (web) and Claude Desktop -> one claude.ai custom-connector system, connecting from Anthropic's servers -> public HTTPS required. `connect-mcp.mdx` gains the constraint it never stated at all, and points a local/intranet reader at the Claude Code section. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01DapQyvYrFb1MxSYe7BL2nt --- ...custom-connector-reaches-from-anthropic.md | 14 ++++++++++ content/docs/ai/agents.mdx | 25 ++++++++++------- content/docs/ai/connect-mcp.mdx | 16 +++++++++++ packages/mcp/README.md | 27 ++++++++++++++----- 4 files changed, 66 insertions(+), 16 deletions(-) create mode 100644 .changeset/mcp-readme-custom-connector-reaches-from-anthropic.md diff --git a/.changeset/mcp-readme-custom-connector-reaches-from-anthropic.md b/.changeset/mcp-readme-custom-connector-reaches-from-anthropic.md new file mode 100644 index 00000000000..cb387743261 --- /dev/null +++ b/.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. diff --git a/content/docs/ai/agents.mdx b/content/docs/ai/agents.mdx index d2b0540c43b..9750c3bb0a9 100644 --- a/content/docs/ai/agents.mdx +++ b/content/docs/ai/agents.mdx @@ -83,19 +83,26 @@ Per client: | Client | How to connect | |---|---| | **Claude Code** | `claude mcp add --transport http objectstack https:///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. | **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. ## You extend the platform with **skills**, not agents diff --git a/content/docs/ai/connect-mcp.mdx b/content/docs/ai/connect-mcp.mdx index 876d4502ec2..79a94a0a7f3 100644 --- a/content/docs/ai/connect-mcp.mdx +++ b/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. + +**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. + + ## Any MCP client (`.mcp.json`) Clients that read an `mcpServers` map connect the same way. With an API key: diff --git a/packages/mcp/README.md b/packages/mcp/README.md index cfd4442eb58..7669351499d 100644 --- a/packages/mcp/README.md +++ b/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