From 680f338de454b29dfe0285efe502127fa205fe7c Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 14 Sep 2026 05:56:39 +0000 Subject: [PATCH] docs(mcp): name the Account door for Connect an Agent, not Setup alone MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit #17646 delivered #16746's ruling as a `navigationContributions` entry in the `account` app and deliberately left Setup gated, so a non-admin reaches the Connect-an-Agent page — but at none of the paths the shipped texts named. - `packages/mcp/src/plugin.ts` — the stdio refusal message now names both doors (Account → Developer for any signed-in user; Setup for admins). - `packages/mcp/README.md` — same, in the `OS_MCP_STDIO_API_KEY` paragraph. - `content/docs/ai/connect-mcp.mdx` — the "Headless: API keys" section now gives both doors with their console URLs, and moves the revoke location to `Account → Developer → API Keys` for the user's own keys, noting the tenant-wide Setup list needs `manage_platform_settings`. The `OS_MCP_SERVER_ENABLED=false` callout no longer calls it a Setup page. Paths, labels and permissions read off the tree, not invented: the account entry at `packages/mcp/src/connect-ui.ts`, the group at `packages/platform-objects/src/apps/account.app.ts`, the package id at `packages/apps/account/src/index.ts`, and the route resolution in objectui's `packages/app-shell/src/utils/appRoute.ts`. Claude-Session: https://claude.ai/code/session_012GKcPZbMoGq7WPzKLfRBTU Co-authored-by: Claude --- .../17648-connect-agent-account-path.md | 20 ++++++++++++ content/docs/ai/connect-mcp.mdx | 31 +++++++++++++------ packages/mcp/README.md | 4 ++- packages/mcp/src/plugin.ts | 4 ++- 4 files changed, 48 insertions(+), 11 deletions(-) create mode 100644 .changeset/17648-connect-agent-account-path.md diff --git a/.changeset/17648-connect-agent-account-path.md b/.changeset/17648-connect-agent-account-path.md new file mode 100644 index 0000000000..9031923f0d --- /dev/null +++ b/.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. diff --git a/content/docs/ai/connect-mcp.mdx b/content/docs/ai/connect-mcp.mdx index 79a94a0a7f..cf4326eb0c 100644 --- a/content/docs/ai/connect-mcp.mdx +++ b/content/docs/ai/connect-mcp.mdx @@ -11,7 +11,8 @@ about the only thing left to do: **connecting a client and proving it works**. 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). @@ -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: diff --git a/packages/mcp/README.md b/packages/mcp/README.md index 7669351499..6a9faa85da 100644 --- a/packages/mcp/README.md +++ b/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. diff --git a/packages/mcp/src/plugin.ts b/packages/mcp/src/plugin.ts index 673907e8d5..1e65297f15 100644 --- a/packages/mcp/src/plugin.ts +++ b/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).', ); }