docs: update MCP server deployment & agent selection

[keydunov]

Summary

Updates the inbound MCP server docs (docs/integrations/mcp-server.mdx) to match the deployment default / allow-list work that shipped in cubejs-enterprise (PR #12596). The old "MCP Defaults" model (a single default deployment + default agent set by admins) no longer reflects the product.

Changes

• Overview — replace the "Agent selection: MCP Defaults" bullet with Deployment selection: clients land on the tenant default deployment (or first accessible) and can target a deployment/agent per request.
• Admin setup — replace "Set MCP Defaults" with Configure deployment access (Admin → MCP Server → Deployment Access): default deployment (incl. "Automatic"), the "Limit available deployments" switch, and the available-deployments picker; note that access is intersected with role-based permissions.
• New section — Select a deployment and agent — documents listDeployments (Auto agent = agentId: null), the chat tool's optional deploymentId/agentId with session-default fallback, loadQueryResults, a Steps workflow, and 403 allow-list enforcement.
• Available actions / Troubleshooting — add discovery + per-request targeting; drop the stale "MCP defaults are not configured" entry and add the 403 Deployment <id> is not available via MCP for this account case.
• Refresh admin paths to Admin → MCP Server.
• Replace the stale MCP Defaults screenshot with a {/* TODO: screenshot */} placeholder for the new Deployment Access section.

All behavior verified against the merged enterprise code (packages/ai-engineer/src/mcp-server.ts, McpEmbedSessionService, McpOAuthService, McpDeploymentAccessSettings.tsx).

Follow-up

• A screenshot of the new Deployment Access admin section still needs to be captured and dropped in where the TODO placeholder sits.

🤖 Generated with Claude Code

[claude]

Claude finished @keydunov's task in 1m 22s —— View job

---

Review: MCP server deployment & agent selection docs

Verdict: content accurately reflects the new deployment-access model and is well-structured. One pre-existing rendering bug worth fixing while you're in the file, plus a few small polish items posted inline.

Findings — 0 high, 1 medium, 4 low

Tasks

• Read PR diff and full file
• Verify against CLAUDE.md conventions (Mintlify, /docs-mintlify active)
• Cross-check Overview / Admin setup / new section / Troubleshooting for consistency
• Post inline findings
• Summarize

Inline comments posted

Sev	Location	Issue
Medium	line 75–80	Numbered list goes 1, 2, 3, 2, 3, 4 — restart bug, fixable now
Low	line 3	Frontmatter description still says "admin-managed defaults"
Low	line 63	Screenshot TODO — make sure it's tracked; the new section leans on it more than the old one
Low	line 189–202	<Steps> skips loadQueryResults even though it's introduced as one of the three tools
Low	line 181	Worth verifying that MCP clients can actually pass null (vs. just omit) for agentId

Things that look good

• Overview/Admin/new section/Troubleshooting all align on the same terminology (deployment access, allow-list, Auto agent).
• New 403 error case is wired through both the explanatory section and Troubleshooting.
• [ref-roles] link reused correctly in the new <Note>.
• Mintlify components (<Note>, <Steps>/<Step>, MDX comment placeholder) used per the local CLAUDE.md.
• No mention of /docs legacy edits — correctly scoped to /docs-mintlify.

Out of scope

• Did not run yarn dev to render the page (docs-only change, no build risk introduced by the diff itself).

· `artyom/mcp-deployment-access-docs`

[claude]

Minor: the prose introduces three tools (listDeployments, chat, loadQueryResults) but the <Steps> workflow only covers the first two. A reader skimming Steps as the canonical workflow won't see where loadQueryResults fits. Either add a fourth Step for pagination, or note in the bullet that loadQueryResults is called only when a chat response is truncated — so it's clear it isn't part of the normal flow.

[claude]

Nit: "When omitted or null" — worth double-checking against packages/ai-engineer/src/mcp-server.ts whether MCP clients can actually pass null for agentId, or whether only omission produces Auto. If the JSON schema marks it optional but not nullable, "or null" is misleading. (The PR description says this was verified — leaving as a callout to confirm.)

[claude]

Pre-existing numbering bug worth fixing while you're touching this block: the steps in this list go 1, 2, 3, 2, 3, 4 (lines 75–80) — the second "2." and "3." restart the count. Markdown will renumber on render, but the source is confusing.

Suggested change

	1. Run the command copied from **Admin → MCP Server → AI Clients → Claude Code**.
	1. Run the command copied from **Admin → MCP Server → AI Clients → Claude Code**.

…and renumber the following lines 2.–6. to match.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cubed3	🟢 Ready	View Preview	Jun 18, 2026, 1:22 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[claude]

Claude finished @keydunov's task in 1m 8s —— View job

---

Review: MCP server deployment & agent selection docs (sync)

Verdict: new commit 69c06f5 swaps the TODO placeholder for the real Deployment Access screenshot and converts the plan callout to <Note> — both good. Three prior threads still apply against the current file; one (screenshot tracking) is now resolved.

Findings — 0 high, 1 medium, 2 low (+ 1 unposted nit)

Tasks

• Pull latest commits, diff against base
• Re-check prior review threads against current file
• Resolve threads that the new commit addressed
• Skip duplicate inline comments for issues already raised

Status of prior threads

Sev	Location	Status
Medium	line 77	Still applies — list still goes 1, 2, 3, 2, 3, 4. Source numbering not yet renumbered.
Low	line 183	Still applies — agentId is still documented as "omitted or null". Worth a quick confirm against packages/ai-engineer/src/mcp-server.ts.
Low	line 204	Still applies — <Steps> still skips loadQueryResults.
Low	screenshot TODO	Resolved — images/docs/integrations/mcp-deployment-access.png added in 69c06f5; thread resolved.

Other observations on the new commit

• <Info> → <Note> swap on the plan/role callout (line 8) is fine — both render similarly in Mintlify and <Note> matches the rest of the page.
• Frontmatter description (line 3) still ends with "admin-managed defaults" — slightly stale now that the section is Deployment Access with allow-list + per-request targeting. Low priority, not posting inline; consider rephrasing to e.g. "…with OAuth and admin-managed deployment access."
• New screenshot's alt text is descriptive of the three controls — nice.

Re-affirmed 3 prior threads still apply; not re-posting to avoid duplicates.

· `artyom/mcp-deployment-access-docs`

[claude]

Claude finished @keydunov's task in 50s —— View job

---

Review: MCP server deployment & agent selection docs (re-sync)

Verdict: no new commits since the previous sync — HEAD is still b037d2f. The three prior unresolved threads still apply; no new findings.

Findings — 0 high, 1 medium, 2 low (re-affirmed)

Tasks

• Re-fetch and diff against base
• List existing review threads, dedup against current state
• Confirm each open thread still applies
• Skip duplicate inline comments

Status of prior threads

Sev	Location	Status
Medium	line 77–82	Still applies — list still goes 1, 2, 3, 2, 3, 4.
Low	line 183	Still applies — agentId still documented as "omitted or null".
Low	line 204	Still applies — <Steps> still skips loadQueryResults.
Low	screenshot TODO	Resolved in b037d2f (prior sync).

Re-affirmed 3 prior threads still apply; not re-posting to avoid duplicates.

· `artyom/mcp-deployment-access-docs`

[claude]

Claude finished @keydunov's task in 34s —— View job

---

Review: MCP server deployment & agent selection docs (re-sync)

Verdict: new commit 49342f2 flips MCP Connectors from preview → GA — <Warning> swapped for <Note> with the standard Premium/Enterprise plan-availability line. Matches the docs-mintlify convention (only preview features carry the <Warning> callout). No new findings on that file. Three prior threads on mcp-server.mdx still apply.

Findings — 0 high, 1 medium, 2 low (re-affirmed)

Tasks

• Pull latest commits, diff against base
• Review new 49342f2 (MCP Connectors GA)
• Re-check existing review threads against current file
• Dedup against prior inline comments

New commit 49342f2 — docs-mintlify/admin/ai/mcp-connectors.mdx

• Removes preview <Warning> (with support-team contact line) and replaces it with a <Note> pointing to Premium and Enterprise plans.
• Consistent with docs-mintlify/CLAUDE.md: the preview <Warning> is required only while a feature is in preview; removing it on GA is correct.
• Tone matches surrounding plan-availability callouts elsewhere in the docs.
• No other content changed — the rest of the page (concepts, adding a connector, authentication, permissions, related cards) is unchanged.

Status of prior threads on mcp-server.mdx

Sev	Location	Status
Medium	line 77	Still applies — list still numbers 1, 2, 3, 2, 3, 4.
Low	line 183	Still applies — agentId still documented as "omitted or null".
Low	line 204	Still applies — <Steps> still skips loadQueryResults.
Low	screenshot TODO	Resolved in b037d2f (prior sync).

Re-affirmed 3 prior threads still apply; not re-posting to avoid duplicates.

· `artyom/mcp-deployment-access-docs`