Claude Code から Databricks の managed MCP server を使う

このポストについて

Databricks Advent Calendar 2025 シリーズ2、8日目の記事。
Databricks 公式の managed MCP server の Claude Code からの利用について書いていく。

記事の概要

Databricks の managed MCP server (DBSQL) を Claude Code から利用し、AI エージェントによる Databricks へのクエリ実行を可能にする方法を解説
dbt model 開発などのデータエンジニアリング作業において、Claude Code が自律的にデータベースの状況を確認できるようにすることで、開発効率を向上
Claude Code の hooks 機能を活用し、破壊的なクエリ（INSERT, CREATE TABLE など）の実行を制限することでセキュリティを担保
Databricks CLI を使った短命 PAT の自動取得により、認証情報を設定ファイルにベタ書きせず安全に認証を実現
具体的な設定ファイル（.claude/settings.json, .mcp.json, shell script）の実例と、実際の動作例を提示

Prerequisites

Claude Code v2.0.60
Databricks CLI v0.279.0

この記事は2025年12月現在の情報や状況を元に書かれている。
このあたりは変化が早いので、少ししたら情報が古くなっている可能性が高いことにご注意いただければと。

特に Databricks の managed MCP server は現時点では Beta 版となっており、今後インターフェースなどの変更の可能性がある。

Managed MCP Server とは

Use Databricks managed MCP servers | Databricks on Google Cloud

ここで取り上げる “managed MCP server” とは、Databricks が提供するリモートの MCP server だ。
Databricks 自体には様々な機能があるが、現時点では以下の4種の MCP server が提供されている。

Vector search: ベクトル検索インデックスへのクエリ
Genie space: AI/BI Genie space の利用
Unity Catalog functions: Unity Catalog 関数を利用して、事前定義された SQL を実行
🆕 DBSQL: 任意の SQL の実行

少し前まで3種だったが、最近4つ目が追加された模様。
今回はこの4つ目の DBSQL を使用する。

これら managed MCP server は Databricks の notebook やローカル環境などから利用することができる。
今回はローカル開発環境の Claude Code から利用することを考えていく。

なぜ Claude Code から managed MCP server を使うのか

Databricks には SQL editor があるので別に Claude Code からクエリ実行できなくても…と言われれば、まあそれはそう。

一方で dbt model を開発したりなどのデータエンジニア (or アナリティクスエンジニア) 観点だと、何かを開発しているときに現在の database の状況をクエリで確認したいことはよくある。
なので Claude Code などの AI エージェントに作業をさせるときも、AI エージェントにクエリを実行させたい局面が出てくる。

例えば前回の記事では Claude Code を使った dbt model の test-first 開発を紹介したが、テストデータを用意するときに実際の table に含まれている値を使いたいことがある。
実際の table に含まれている値を知るためにはクエリを実行する必要があり、Claude Code が自分でクエリを実行できれば人間の作業を減らすことができるわけだ。

期待する挙動

任意の SQL の実行を行う MCP server の tool として、以下のような挙動を期待する。

LLM が考えた SQL を実行できる
Databricks への認証を安全に行える
破壊的なクエリが実行されない

1点目は当然として、2点目と3点目について補足しておく。

2点目の認証について、Databricks 上の table に対してクエリを実行する場合はもちろん Databricks の認証を通す必要がある。
少し調べたところでは OAuth はこのユースケースでは使えなさそうだったので、PAT (Personal Access Token) を使った認証をすることになる。
しかし PAT の値を設定ファイルにベタ書きすることは避けたい。

3点目について、LLM が考えた SQL を実行するわけだが、LLM がデータの改ざんや table の drop など、開発者の期待しない挙動をしてこないとも限らない。
運用上こういった破壊的なクエリを実行しないこともないが、そういった稀なケースは LLM にまかせずに人間が責任を持ってやる方がいいと現時点では考えている。
よって Claude Code から破壊的なクエリは実行できないようにしたい。

動作イメージ

期待する挙動を実現するための諸々の設定を行った結果の実際の動作を示す。
(設定については後述)

まずは session 開始からの通常の非破壊的なクエリの実行。

> table `my_catalog.my_schema.orders` のスキーマを教えて。 

⏺ databricks_sql - execute_sql_read_only (MCP)(query: "DESCRIBE TABLE my_catalog.my_schema.orders")
  ⎿  {                                                        
       "statement_id": "********-****-****-****-************",
       "status": {
     … +4 lines (ctrl+o to expand)

⏺ databricks_sql - poll_sql_result (MCP)(statement_id: "********-****-****-****-************")
  ⎿  {                                                        
       "statement_id": "********-****-****-****-************",
       "status": {
     … +147 lines (ctrl+o to expand)

⏺ my_catalog.my_schema.orders テーブルのスキーマは以下の通りです：

  | カラム名                 | データ型   |
  |----------------------|--------|
  | order_id             | bigint |
  | customer_id          | bigint |
  | order_date           | date   |
  | status               | string |
  | credit_card_amount   | double |
  | coupon_amount        | double |
  | bank_transfer_amount | double |
  | gift_card_amount     | double |
  | amount               | double |

  注文情報を格納するテーブルで、各支払い方法（クレジットカード、クーポン、銀行振込、ギフトカード）ごとの金額と合計金額（amount）が記録される構造になっています。

(暗黙的に) 認証が通っており、クエリが実行されて結果を取得できることを確認。
次にあえて破壊的なクエリ (ここでは table 作成) をやろうとしてみる。

  > Databricks の schema `my_catalog.my_schema` の下に table `my_table` を作って。int 型の `id` という column 
が1つあればよい。 

⏺ Databricks に my_catalog.my_schema.my_table テーブルを作成します。

⏺ databricks_sql - execute_sql (MCP)(query: "CREATE TABLE my_catalog.my_schema.my_table (\n  id INT\n)")
  ⎿  PreToolUse:mcp__databricks_sql__execute_sql hook returned blocking error
  ⎿  Error: execute_sql is NOT allowed. Use execute_sql_read_only instead.

⏺ 申し訳ありませんが、現在の環境では execute_sql
  ツール（書き込み操作）が制限されており、execute_sql_read_only（読み取り専用）のみ使用可能です。

  そのため、テーブル作成（CREATE TABLE）のような DDL 操作を実行することができません。

  テーブルを作成するには、以下のいずれかの方法をお試しください：

  1. Databricks SQL Editor で直接実行する
  2. Databricks Notebook で実行する
  3. 管理者に権限の変更を依頼する

  参考までに、実行すべき SQL は以下です：

  CREATE TABLE my_catalog.my_schema.my_table (
    id INT
  )

期待どおり、破壊的なクエリの実行は許可されなかった。

設定例

では上記の挙動を実現するための設定を見ていく。

.claude/settings.json

{
  "env": {
    "DATABRICKS_WORKSPACE_PROFILE": "my_workspace"
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__databricks_sql__execute_sql",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"deny\", \"permissionDecisionReason\": \"execute_sql is NOT allowed. Use execute_sql_read_only instead.\"}}'"
          }
        ]
      },
      {
        "matcher": "mcp__databricks_sql__poll_sql_result",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"allow\"}}'"
          }
        ]
      }
    ]
  }
}

DATABRICKS_WORKSPACE_PROFILE は Databricks CLI による認証時に使用するプロファイル名 (後述)。

hooks においては PreToolUse イベントで MCP server の tool 使用を制御しているが、それを説明する前に managed MCP server DBSQL の tool について記載しておく。
DBSQL には次の3つの tool がある。

execute_sql: SELECT に加え、INSERT, UPDATE, CREATE TABLE, ALTER TABLE など破壊的なものも含めた SQL の実行
execute_sql_read_only: read only の非破壊的な SQL の実行
poll_sql_result: SQL の結果を polling

それぞれの詳細は Claude Code の /mcp コマンドで確認できる。

期待される挙動として、ここでは execute_sql は Claude Code から実行できないようにしたい。
Hooks reference - Claude Code Docs によると、PreToolUse イベントにおいて "matcher": "mcp__<server>__<tool>" により MCP server の tool を補足可能とのこと。
さらに PreToolUse イベントの JSON 出力において permissionDecision フィールドの値として allow, deny, ask を指定し、tool 利用時のエージェントの反応を決めることができる。

上記設定では tool execute_sql は deny にしており、Claude Code により実行を禁止している。
execute_sql_read_only は明示的に記載しておらず default の ask の挙動になっており、実行時にユーザーの許可が必要となっている。
過剰に重いクエリが実行されないよう、人間がチェックする想定としている。
poll_sql_result は allow とされており、こちらはユーザーの許可なしで Claude Code が実行できるようにしている。

これらの hook 設定がない場合は前述のようなプロンプトで普通に execute_sql が実行され、table が作成される。

~/.databrickscfg

[my_workspace]
host      = https://dbc-********-****.cloud.databricks.com/
auth_type = databricks-cli

後述の Databricks CLI で認証を通すときのプロファイルの設定。
これは一例であり、別の認証方式でも別にいい。

.mcp.json

{
  "mcpServers": {
    "databricks_sql": {
      "type": "stdio",
      "command": "sh",
      "args": [
        ".claude/mcp/databricks_sql.sh"
      ]
    }
  }
}

通常はここで "command": "npx" として直接コマンドを書くが、ここでは wrapper の shell script を呼び出すようにしている。
shell で認証まわりの雑務もやるようにしている。

.claude/mcp/databricks_sql.sh

#!/bin/bash
set -eu

# Set host name and personal access token for Databricks workspace
databricks auth login -p $DATABRICKS_WORKSPACE_PROFILE
DATABRICKS_WORKSPACE_HOSTNAME=`databricks auth describe -p $DATABRICKS_WORKSPACE_PROFILE -o json | jq -r '.details.host'`
DATABRICKS_PERSONAL_ACCESS_TOKEN=`databricks auth token -p $DATABRICKS_WORKSPACE_PROFILE -o json | jq -r '.access_token'`

# Launch MCP remote for Databricks SQL
npx mcp-remote \
    $DATABRICKS_WORKSPACE_HOSTNAME/api/2.0/mcp/sql \
    --header "Authorization: Bearer $DATABRICKS_PERSONAL_ACCESS_TOKEN"

認証、PAT の取得、MCP server の実行を行っている。
都度手動、またはプロンプトで認証を通すよりは MCP server の接続時に暗黙的に認証が通ってしまった方が楽だと考え、このようにした。
databricks auth token では1時間で expire される PAT が発行され、それを使うようにしている。
なので Claude Code の session 開始時に MCP server に接続した後、1時間以上経過した場合は Reconnect の手間が必要になる。

1時間だと短い場合は databricks token create --lifetime-seconds 7200 のようにすることもできるが、こちらのコマンドは接続のたびに PAT を増やしていく挙動になるのでそれも微妙だなということでこうなっている。

このようにして短命の PAT を使い、かつ設定ファイルにベタ書きしないことである程度セキュリティに配慮しているが、正直認証のところはより良いやり方がありそうだと思っている。

この shell script は session 開始時や Reconnect 時などに呼ばれる。
プロファイルを前述のような設定にしている場合、都度 web のログイン画面が開いて SSO などでのログインが必要となる。

所感

これで test-first 開発を含め、データ基盤の開発をやりやすくなった。
Claude Code からの利用はあくまで開発の補助であり、データ分析をしたい場合は notebook からの MCP server 利用や Genie space UI を使う方がいいだろう。

hooks 設定は実行前の SQL レビューなど他にも色々できそうだと思う反面、JSON で頑張って書くのはなかなかしんどい。
というのを考えると syou6162/cc-pre-tool-use-hook-judge みたいなものを開発したくなるってくるというのがよくわかった。

このポストについて#

記事の概要#

Prerequisites#

Managed MCP Server とは#

なぜ Claude Code から managed MCP server を使うのか#

期待する挙動#

動作イメージ#

設定例#

.claude/settings.json#

~/.databrickscfg#

.mcp.json#

.claude/mcp/databricks_sql.sh#

所感#