Refactor aitools into command group with mcp subcommand (#4303)

## Summary
Separates the `databricks experimental aitools` command into a proper
command group by moving the MCP server functionality to a new `mcp`
subcommand.

## NOTE

This is a breaking change. Users who have installed the MCP after we
renamed it from `apps-mcp` to `aitools` will have a broken MCP
configuration and need to run the install command again. We are not
ingesting in a clean migration we have because it has not released this
widely yet and it hasn't been out for long.

## Changes
- `aitools` is now a command group with no default action
- New `mcp` subcommand starts the MCP server: `databricks experimental
aitools mcp`
- Updated installation scripts (Claude Code, Cursor) to use the new
command structure
- Updated documentation and examples

## Before
```bash
databricks experimental aitools  # started MCP server
```

## After
```bash
databricks experimental aitools mcp  # starts MCP server
```

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: fjakobs

experimental/aitools/README.md

@@ -94,7 +94,7 @@ If you prefer to configure manually or the automatic installation doesn't work:
   "mcpServers": {
     "databricks": {
       "command": "databricks",
-      "args": ["experimental", "aitools"],
+      "args": ["experimental", "aitools", "mcp"],
       "env": {
         "DATABRICKS_HOST": "https://your-workspace.databricks.com",
         "DATABRICKS_TOKEN": "dapi...",
@@ -156,7 +156,7 @@ If the MCP server doesn't connect or shows errors:
 5. **Check Databricks CLI:** Verify the CLI is installed and accessible:
    ```bash
    databricks --version
-   databricks experimental aitools --help
+   databricks experimental aitools mcp --help
    ```
 
 6. **Test authentication:** Try listing catalogs to verify credentials work:
@@ -323,8 +323,8 @@ The `invoke_databricks_cli` tool:
 # Install MCP server in coding agents (Claude Code, Cursor, etc.)
 databricks experimental aitools install
 
-# Start MCP server (default mode)
-databricks experimental aitools
+# Start MCP server
+databricks experimental aitools mcp
 ```
 
 ### Environment Variables

experimental/aitools/cmd/aitools.go

@@ -13,14 +13,33 @@ import (
 )
 
 func NewMcpCmd() *cobra.Command {
-	var warehouseID string
-
 	cmd := &cobra.Command{
 		Use:     "aitools",
 		Aliases: []string{"apps-mcp"},
 		Hidden:  true,
 		Short:   "Databricks AI Tools - Model Context Protocol server for AI agents",
-		Long: `Start and manage an MCP server that provides AI agents with tools to interact with Databricks.
+		Long: `Manage Databricks AI Tools and Model Context Protocol server.
+
+Provides commands to:
+- Start an MCP server for AI agents (mcp)
+- Install the MCP server in coding agents (install)
+- Access MCP tools directly (tools)`,
+	}
+
+	cmd.AddCommand(newMcpCmd())
+	cmd.AddCommand(newInstallCmd())
+	cmd.AddCommand(newToolsCmd())
+
+	return cmd
+}
+
+func newMcpCmd() *cobra.Command {
+	var warehouseID string
+
+	cmd := &cobra.Command{
+		Use:   "mcp",
+		Short: "Start the Model Context Protocol server",
+		Long: `Start an MCP server that provides AI agents with tools to interact with Databricks.
 
 The MCP server exposes the following capabilities:
 - Data exploration (query catalogs, schemas, tables, execute SQL)
@@ -29,7 +48,7 @@ The MCP server exposes the following capabilities:
 
 The server communicates via stdio using the Model Context Protocol.`,
 		Example: `  # Start MCP server with required warehouse
-  databricks experimental aitools --warehouse-id abc123`,
+  databricks experimental aitools mcp --warehouse-id abc123`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			// Create cancellable context for graceful shutdown
 			ctx, cancel := context.WithCancel(cmd.Context())
@@ -82,8 +101,5 @@ The server communicates via stdio using the Model Context Protocol.`,
 	// Define flags
 	cmd.Flags().StringVar(&warehouseID, "warehouse-id", "", "Databricks SQL Warehouse ID")
 
-	cmd.AddCommand(newInstallCmd())
-	cmd.AddCommand(newToolsCmd())
-
 	return cmd
 }

experimental/aitools/cmd/tools.go

@@ -8,8 +8,9 @@ import (
 func newToolsCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:    "tools",
-		Short:  "MCP tools for AI agents",
-		Hidden: true,
+		Short:  "CLI tools for AI agents",
+		Long:   `CLI tools to be used by AI agents. These tools are optimized for AI coding agents like Claude Code and Cursor. The tools can change at any time. There are no stability guarantees for these tools.`,
+		Hidden: false,
 	}
 
 	cmd.AddCommand(newQueryCmd())

experimental/aitools/lib/agents/claude.go

@@ -32,7 +32,7 @@ func InstallClaude() error {
 		"--transport", "stdio",
 		"databricks-mcp",
 		"--",
-		databricksPath, "experimental", "aitools")
+		databricksPath, "experimental", "aitools", "mcp")
 
 	output, err := cmd.CombinedOutput()
 	if err != nil {

experimental/aitools/lib/agents/cursor.go

@@ -84,7 +84,7 @@ func InstallCursor() error {
 	// Add or update the Databricks AI Tools MCP server entry
 	config.McpServers["databricks-mcp"] = mcpServer{
 		Command: databricksPath,
-		Args:    []string{"experimental", "aitools"},
+		Args:    []string{"experimental", "aitools", "mcp"},
 	}
 
 	// Write back to file with pretty printing

experimental/aitools/lib/agents/custom.go

@@ -12,15 +12,15 @@ func ShowCustomInstructions(ctx context.Context) error {
 To install the Databricks CLI MCP server in your coding agent:
 
 1. Add a new MCP server to your coding agent's configuration
-2. Set the command to: "databricks experimental aitools"
+2. Set the command to: "databricks experimental aitools mcp"
 3. No environment variables or additional configuration needed
 
 Example MCP server configuration:
 {
   "mcpServers": {
     "databricks": {
       "command": "databricks",
-      "args": ["experimental", "aitools"]
+      "args": ["experimental", "aitools", "mcp"]
     }
   }
 }