Document the One integration - #34

What changed and why

The ref.tools integrations grid promises "250+ sources via the One integration", but there was no page behind that claim. This adds plans/integrations/one.mdx, which explains what One actually is — a pre-configured remote MCP server Ref connects in one click over OAuth — walks through connecting it from Settings, and defers everything else (agent reach, per-thread attachment, transport/auth support) to the existing Custom MCP Servers page rather than restating it. Also adds the page to the Integrations nav group and one row to the context-sources table on the Integrations overview.

Verified

All in ref-tools/ref, principally plan-app/client/src/components/settings/McpServersSection.tsx:

• Where the control lives — McpServersSection renders the MCP Servers section, and it is mounted by IntegrationsSettingsPage, which SettingsModal.tsx maps to the nav item labelled Integrations (line 97). Hence "Settings > Integrations > MCP Servers".
• The in-product copy — the page reuses the product's own sentence verbatim in substance: "Connect your agent to 250+ apps through One — search, read docs, and execute actions across Gmail, Slack, HubSpot, Stripe, and more. Browse available apps." (McpServersSection.tsx:629-652), including both link targets https://www.withone.ai and https://www.withone.ai/knowledge. Asserted in McpServersSection.component.test.tsx:218-228. No claim about catalogue size or coverage goes beyond that sentence.
• One-click connect — handleConnectOne (McpServersSection.tsx:559-575) calls saveMcpServer({ name: 'one', url: 'https://mcp.withone.ai/mcp' }) from the constants at lines 33-34, then startOAuthFor when the save comes back needsAuth. startOAuthFor → startMcpOAuth → openOAuthPopup (lines 64-113), i.e. a popup window. The component test "saves the One preset and starts the standard OAuth popup" asserts exactly this call sequence.
• Server name one — saved name: 'one'; slugifyMcpServerName (plan-app/shared/mcpServerName.ts) leaves it unchanged, and the per-thread connectors menu labels MCP rows with server.name (plan-app/client/src/components/chat/ConnectorsMenu.tsx:145-156).
• Re-check after authorizing, then a stored tool list — the OAuth callback re-runs testMcpServerConnection and writes status: 'verified' plus the reported tools (plan-app/server/src/routes/mcpOAuth.ts:186-199). The settings card then renders the tool count as an expandable list of names and descriptions (McpServersSection.tsx:672-761).
• The Connect One button is conditional — gated on hasOneServer, computed by matching the One URL against the configured servers (McpServersSection.tsx:619, 629). The test "hides the One preset when a server with the One URL already exists" confirms both the button and the explainer disappear once connected.
• Enabled / Connect / Remove behaviour — Enabled maps to setMcpServerEnabled; getAttachableMcpServers (plan-app/server/src/services/mcpServerConnection.ts:330-345) attaches enabled+verified servers by default, and a per-thread override list replaces the enabled flag, which is why a thread can still select a disabled server. The Connect button renders only for status === 'needs_auth' and re-enters the same popup flow. Remove deletes the config, which restores the Connect One prompt.
• Not gated — the One preset renders unconditionally; the only feature flag in McpServersSection is the one behind the Form/JSON panel and the Edit button, so neither is mentioned on the page. (A withone entry exists in FeatureFlags but is referenced nowhere.)

Unverified / omitted

• Cost. Nothing in the product repo says who pays for One, whether it consumes Ref credits, or which tiers can connect it. Omitted entirely — a reader will ask, and the answer needs a human. Unblocked by a statement from whoever owns the One relationship.
• Catalogue detail. The page claims exactly "250+ apps" and the five example apps the product itself names, and links to One's own directory instead of enumerating anything. No count, freshness, or coverage claim beyond the product's sentence.
• Team scope / sharing. MCP server configs are stored per user, but the Custom MCP Servers page already states that in its support table, so the One page links rather than repeating it.
• Tool naming. Custom MCP tools reach the agent as mcp__<server>__<tool>, so One's tools are prefixed one. Left out as internal-facing detail that the Custom MCP Servers page does not cover either.
• Editing the One connection. The Edit button in the MCP Servers list is behind a rollout flag, so the page does not mention it.

Conflicts

docs.json is edited (one line added to the Integrations group) — sibling PRs in this batch also touch it; conflicts should be one-line and trivial. plans/integrations/overview.mdx is also edited, but only one row appended to the context-sources table, which is a different hunk from the agent tables a sibling PR is working on. plans/integrations/custom-mcp.mdx is untouched.

Generated by Claude Code