docs(mcp): name the Account door for Connect an Agent, not Setup alone

.changeset/17648-connect-agent-account-path.md

@@ -0,0 +1,20 @@
+---
+'@objectstack/mcp': patch
+---
+
+Point Connect-an-Agent instructions at the Account door too, so a non-admin is told a path they can actually take
+
+#17646 made the Connect-an-Agent page reachable for every signed-in user by
+adding a second `navigationContributions` entry into the **`account`** app's
+`grp_account_developer` group. It deliberately did **not** ungate Setup — that
+was measured to expose 14+ unrelated Setup surfaces — so the same principal
+still gets `403 PERMISSION_DENIED` on `GET /api/v1/meta/apps/setup`.
+
+The shipped instructions never moved. The stdio transport's refusal message and
+this package's README both said *"Setup → Connect an Agent"*, naming the one app
+a non-admin cannot open — read, in the refusal's case, at exactly the moment the
+user is stuck. Both now name **both** doors: **Account → Developer** for any
+signed-in user, **Setup → Connect an Agent** for platform admins. The Setup
+entry is unchanged and stays where admins already look.
+
+Text only — no behaviour, no gate, no authorization change.

content/docs/ai/connect-mcp.mdx

@@ -11,7 +11,8 @@ about the only thing left to do: **connecting a client and proving it works**.
 
 <Callout type="info">
 To turn the surface off, set `OS_MCP_SERVER_ENABLED=false` — the endpoint then
-returns 404 and the **Setup → Connect an Agent** page disappears with it. See
+returns 404 and the **Connect an Agent** page disappears with it, along with
+both its Setup and Account navigation entries. See
 [environment variables](/docs/deployment/environment-variables#mcp-server).
 </Callout>
 
@@ -94,14 +95,26 @@ Clients that read an `mcpServers` map connect the same way. With an API key:
 
 ## Headless: API keys
 
-Mint a key from **Setup → Connect an Agent** in the Console: the page lives at
-`/_console/apps/com.objectstack.setup/page/connect_agent` (a link in the Setup
-sidebar takes you there), and the **Create key** button sits at the bottom
-under *API keys*. The new key is shown **once**, together with a ready-to-paste
-`x-api-key: osk_...` header line — copy it before you dismiss the panel. The
-same page carries copy-paste connect snippets for Claude Code, Claude Desktop,
-Cursor, VS Code, and Codex, and a download link for the app's `SKILL.md`.
-Existing keys are listed (prefix only) and revoked under **Setup → API keys**.
+Mint a key from the **Connect an Agent** page in the Console. One page, two
+doors — which one you have depends on your permissions:
+
+- **Any signed-in user** — open the avatar menu (top right) → **Profile** to
+  enter the Account app, then **Developer → Connect an Agent** in its sidebar.
+  Direct link: `/_console/apps/com.objectstack.account/page/connect_agent`.
+- **Platform admins** — **Setup → Connect an Agent**, at
+  `/_console/apps/com.objectstack.setup/page/connect_agent`, reached from the
+  Setup sidebar. The Setup app requires the `setup.access` permission, so this
+  door alone is not enough for an ordinary member; the Account one needs none.
+
+On the page, the **Create key** button sits at the bottom under *API keys*. The
+new key is shown **once**, together with a ready-to-paste `x-api-key: osk_...`
+header line — copy it before you dismiss the panel. The same page carries
+copy-paste connect snippets for Claude Code, Claude Desktop, Cursor, VS Code,
+and Codex, and a download link for the app's `SKILL.md`.
+
+Your own keys are listed (prefix only) and revoked under **Account → Developer
+→ API Keys**. Platform admins get the tenant-wide list at **Setup → Access
+Control → API Keys**, which requires `manage_platform_settings`.
 
 Or mint one over REST:
 

packages/mcp/README.md

@@ -89,7 +89,9 @@ or the `autoStart` option.
 
 `OS_MCP_STDIO_API_KEY` is not optional and has no fallback: a stdio server with
 no resolvable principal **refuses to start** rather than serving data unscoped
-(ADR-0101). Mint a key in Setup → Connect an Agent, or `POST /api/v1/keys`.
+(ADR-0101). Mint a key on the **Connect an Agent** page — under **Account →
+Developer** for any signed-in user, or **Setup → Connect an Agent** for
+platform admins — or `POST /api/v1/keys`.
 
 The legacy `MCP_SERVER_*` spellings are still honoured with a deprecation
 warning.

packages/mcp/src/plugin.ts

@@ -381,7 +381,9 @@ export class MCPServerPlugin implements Plugin {
       if (!apiKey) {
         throw new Error(
           '[MCP] The stdio transport is enabled (OS_MCP_STDIO_ENABLED / autoStart) but OS_MCP_STDIO_API_KEY is not set. ' +
-            'stdio must run under a real identity — mint an API key (Setup → Connect an Agent, or POST /api/v1/keys) and set ' +
+            'stdio must run under a real identity — mint an API key on the Connect an Agent page ' +
+            '(Account → Developer for any signed-in user; Setup → Connect an Agent for admins), ' +
+            'or POST /api/v1/keys, and set ' +
             'OS_MCP_STDIO_API_KEY=osk_.... Refusing to start an unscoped stdio server (ADR-0101).',
         );
       }