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

docs/cli/overview.mdx

@@ -87,6 +87,8 @@ cn -p "Update documentation based on recent code changes"
 
   **In headless mode**, tools with "ask" permission are automatically excluded to prevent the AI from seeing tools it cannot call. This ensures reliable automation without user intervention.
 
+  **MCP tools** are excluded in headless mode by default. To enable specific trusted MCP servers in headless workflows, set `allowHeadless: true` in your [MCP server configuration](/customize/deep-dives/mcp#how-to-use-mcp-servers-in-cli-headless-mode).
+
   **In TUI mode**, tools with "ask" permission are available and will prompt for confirmation when the AI attempts to use them.
 
   💡 **Tip**: If your workflow requires tools that need confirmation (like file writes or terminal commands), use TUI mode. For fully automated workflows with read-only operations, use headless mode.

docs/customize/deep-dives/mcp.mdx

@@ -151,6 +151,52 @@ These remote transport options allow you to connect to MCP servers hosted on rem
 
 For detailed information about transport mechanisms and their use cases, refer to the official MCP documentation on [transports](https://modelcontextprotocol.io/docs/concepts/transports#server-sent-events-sse).
 
+### How to Use MCP Servers in CLI Headless Mode
+
+By default, MCP tools are not available in [CLI headless mode](/cli/overview#headless-mode-production-automation) for security reasons. This prevents untrusted tools from executing without user approval during automated workflows.
+
+<Note>
+  **What is headless mode?**
+
+  Headless mode is used for automated, non-interactive workflows like CI/CD pipelines, git hooks, and scripting. In this mode, the CLI cannot prompt for user confirmation.
+</Note>
+
+To enable specific trusted MCP servers in headless mode, add `allowHeadless: true` to your server configuration:
+
+```yaml
+mcpServers:
+  - name: Brave Search
+    command: npx
+    args:
+      - "-y"
+      - "@modelcontextprotocol/server-brave-search"
+    allowHeadless: true  # Enable in headless mode
+    env:
+      BRAVE_API_KEY: ${{ secrets.BRAVE_API_KEY }}
+```
+
+<Warning>
+  **Security consideration:** Only set `allowHeadless: true` for MCP servers you fully trust, as their tools will be able to execute without user confirmation in automated workflows.
+</Warning>
+
+**When to use `allowHeadless`:**
+
+<CardGroup cols={2}>
+  <Card title="✅ Good candidates" icon="check">
+    - Read-only search APIs
+    - Documentation retrieval services
+    - Trusted internal tools
+    - Well-scoped automation utilities
+  </Card>
+
+  <Card title="⚠️ Use with caution" icon="triangle-exclamation">
+    - File system modification tools
+    - Database write operations
+    - External API calls that modify state
+    - Tools with broad permissions
+  </Card>
+</CardGroup>
+
 ### How to Work with Secrets in MCP Servers
 
 With some MCP servers you will need to use API keys or other secrets. You can leverage locally stored environments secrets

docs/reference.mdx

@@ -316,6 +316,7 @@ The [Model Context Protocol](https://modelcontextprotocol.io/introduction) is a
 - `cwd`: An optional working directory to run the command in. Can be absolute or relative path.
 - `requestOptions`: Optional request options for `sse` and `streamable-http` servers. Same format as [model requestOptions](#models).
 - `connectionTimeout`: Optional timeout for _initial_ connection to MCP server
+- `allowHeadless`: Enable this MCP server's tools in [CLI headless mode](/cli/overview#headless-mode-production-automation). Defaults to `false`. When `true`, tools from this server can be used in automated workflows without user confirmation.
 
 **Example:**
 
@@ -333,6 +334,12 @@ mcpServers:
     cwd: /Users/NAME/project
     env:
       NODE_ENV: production
+  - name: Brave Search
+    command: npx
+    args:
+      - "-y"
+      - "@modelcontextprotocol/server-brave-search"
+    allowHeadless: true  # Enable in CLI headless mode for automation
 ```
 
 ### `data`

extensions/cli/src/stream/handleToolCalls.ts

@@ -198,9 +198,21 @@ export async function getRequestTools(isHeadless: boolean) {
       permissionsState.permissions,
     );
 
+    // Allow tool if:
+    // 1. Explicitly allowed in permissions
+    // 2. Permission is "ask" and we're in interactive mode (can prompt user)
+    // 3. MCP tool with allowHeadless=true can upgrade "ask" permission in headless mode
+    //    (but should not override explicit "exclude" permissions)
+    const allowMcpInHeadless =
+      result.permission === "ask" &&
+      !tool.isBuiltIn &&
+      isHeadless &&
+      tool.allowHeadless;
+
     if (
       result.permission === "allow" ||
-      (result.permission === "ask" && !isHeadless)
+      (result.permission === "ask" && !isHeadless) ||
+      allowMcpInHeadless
     ) {
       allowedTools.push(tool);
     }