docs: add allowHeadless documentation for MCP servers in CLI headless mode

[continue]

Documentation Updates for PR #9327

This PR adds documentation for the new allowHeadless configuration option for MCP servers introduced in #9327.

⚠️ Note: This PR should be merged after #9327 is merged.

Changes

Reference Documentation (reference.mdx)

• Added allowHeadless property to mcpServers configuration section
• Added example showing usage with Brave Search MCP server
• Linked to CLI headless mode documentation for context

MCP Deep Dive (customize/deep-dives/mcp.mdx)

• Added comprehensive section "How to Use MCP Servers in CLI Headless Mode"
• Explained security rationale for default behavior
• Provided usage examples with code snippets
• Added Mintlify CardGroup component showing good candidates vs. cautionary use cases
• Included security warning about trusting MCP servers

CLI Overview (cli/overview.mdx)

• Updated tool permissions Info box to mention MCP tools headless behavior
• Added link to detailed MCP headless mode documentation

Documentation Approach

The documentation is scoped to explain the feature without changing the overall level of detail in the docs. It:

• Explains the security model (MCP tools excluded by default in headless mode)
• Shows how to opt-in specific trusted servers with allowHeadless: true
• Provides clear guidance on when to use this feature
• Uses Mintlify components (Note, Warning, CardGroup) for effective information display

Screenshots

Reference Documentation Example

Added allowHeadless property with clear description and usage example:

mcpServers:
  - name: Brave Search
    command: npx
    args:
      - "-y"
      - "@modelcontextprotocol/server-brave-search"
    allowHeadless: true  # Enable in CLI headless mode for automation

MCP Deep Dive Section

Added comprehensive section with:

• Security explanation in Note component
• Usage example with Warning about security considerations
• CardGroup showing appropriate use cases

---

Related: #9327

This task was co-authored by nate and Continue.

---

Summary by cubic

Adds an allowHeadless option for MCP servers to safely enable trusted MCP tools in CLI headless mode, and updates docs with clear guidance and examples.

• New Features
  • Config: allowHeadless boolean on MCP servers (default false).
  • Runtime: only include MCP tools in headless mode when allowHeadless is true; otherwise excluded.
  • Enforcement: upgrades "ask" to allow in headless for MCP tools when allowHeadless=true; never overrides explicit "exclude".
  • Tests: coverage for headless inclusion/exclusion and policy behavior.
  • Docs: updated reference, MCP deep dive, and CLI overview with examples and security considerations.

^{Written for commit 2cfb204. Summary will update automatically on new commits.}

[cubic-dev-ai]

No issues found across 10 files

[continue]

✅ Code Review Issues Fixed

I've addressed both P1 and P2 issues identified by the review:

Issue 1 (P1): Security Fix - Respect Explicit Exclusions

Problem: allowHeadless could bypass explicit tool exclusions in permissions.

Fix: Modified the logic so allowHeadless only upgrades "ask" permissions to automatic approval, not override "exclude" permissions.

// Before: Could bypass exclusions
const allowMcpInHeadless =
  !tool.isBuiltIn && isHeadless && tool.allowHeadless;

// After: Only upgrades "ask" permissions
const allowMcpInHeadless =
  result.permission === "ask" &&
  !tool.isBuiltIn &&
  isHeadless &&
  tool.allowHeadless;

Added test case to verify excluded tools remain excluded even with allowHeadless: true.

Issue 2 (P2): Test Accuracy - Preserve Undefined Values

Problem: Test helper coerced undefined to false, so the test didn't properly verify undefined behavior.

Fix: Changed from ?? false coercion to conditional property spread to preserve actual undefined values.

// Before: Coerced undefined to false
allowHeadless: allowHeadless ?? false,

// After: Preserves undefined
...(allowHeadless !== undefined ? { allowHeadless } : {}),

Both fixes maintain the security-first design while ensuring proper test coverage.

---

Commit: 2cfb204