Metabase

Server MCP Metabase

Metabase menyertakan server bawaan Model Context Protocol (MCP) yang memungkinkan klien AI terhubung langsung ke instans Metabase. Server ini menggunakan https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http dan dibangun di atas Agent API Metabase untuk mengekspos alat-alat untuk mencari, menavigasi, melakukan kueri, memvisualisasikan, dan membuat/memperbarui konten - semuanya dibatasi oleh izin pengguna yang terhubung.

Endpoint

Server MCP tersedia di:

https://{your-metabase.example.com}/api/metabase-mcp

Jalur lawas /api/mcp masih berfungsi sebagai alias untuk klien yang sudah ada, tetapi /api/metabase-mcp adalah URL kanonis yang diiklankan.

Menghubungkan klien

Arahkan klien yang kompatibel dengan MCP ke endpoint /api/metabase-mcp. Misalnya, dengan Claude Code:

claude mcp add metabase https://{your-metabase.example.com}/api/metabase-mcp --transport streamable-http

Untuk Claude Desktop, buat konektor kustom menggunakan URL yang sama.

Untuk Cursor, buka Settings > MCP dan tambahkan server baru dengan tipe yang diatur ke streamable-http dan URL:

https://{your-metabase.example.com}/api/metabase-mcp

Autentikasi

Klien MCP melakukan autentikasi melalui OAuth 2.0. Metabase menjalankan server OAuth tertanamnya sendiri - tidak diperlukan penyedia eksternal.

Alur untuk koneksi pertama kali:

1. Klien menemukan endpoint OAuth Metabase.
2. Klien mendaftarkan dirinya ke Metabase.
3. Pengguna dialihkan ke Metabase untuk masuk dan menyetujui koneksi.
4. Klien menerima token akses yang dibatasi oleh izin Metabase pengguna.

Sesi berbasis browser (auth cookie) juga didukung dan menerima cakupan tanpa batasan.

Cakupan

Token akses dibatasi untuk membatasi alat apa yang dapat digunakan klien:

Cakupan	Memberikan akses ke
agent:search	search
agent:resource:read	read_resource (selalu diberikan kepada pemanggil terautentikasi; pemeriksaan izin per-URI terjadi di dalam dispatcher)
agent:query:construct	construct_query
agent:query	query
agent:query:execute	execute_query
agent:sql:construct	construct_native_query
agent:sql:execute	execute_sql
agent:question:create	create_question
agent:question:update	update_question (juga mencakup "pindahkan kartu ke koleksi" dan pengarsipan)
agent:question:execute	execute_question
agent:metric:create	create_metric
agent:metric:update	update_metric (juga mencakup "pindahkan metrik ke koleksi" dan pengarsipan)
agent:dashboard:create	create_dashboard
agent:dashboard:update	update_dashboard (juga mencakup pengarsipan)
agent:collection:create	create_collection

Pola wildcard (mis. agent:*) cocok dengan cakupan apa pun dengan prefiks tersebut.

Metadata sumber daya yang dilindungi OAuth tersedia di:

/.well-known/oauth-protected-resource/api/metabase-mcp

Secara default, layar persetujuan kami memberikan akses ke semua cakupan tanpa kesempatan untuk menyesuaikan.

Alat yang tersedia

Server MCP mengekspos alat-alat ini, yang dihasilkan secara dinamis dari metadata endpoint Agent API:

Penemuan + baca

Alat	Deskripsi
search	Cari tabel, metrik, kartu, dasbor, dan koleksi menggunakan kueri kata kunci atau bahasa alami.
read_resource	Baca satu atau lebih entitas Metabase berdasarkan URI metabase://. Mencakup navigasi database/skema/tabel/koleksi/pertanyaan/dasbor/metrik/transformasi. Hingga 5 URI per panggilan.

Konstruksi + eksekusi kueri

Alat	Deskripsi
construct_query	Buat kueri terhadap tabel atau metrik. Menerima prompt asli pengguna jika tersedia. Mengembalikan query_handle buram untuk digunakan dengan execute_query atau visualize_query.
construct_native_query	Buat kueri native (SQL mentah) untuk database. Mengembalikan query_handle buram untuk diumpankan ke create_question dan menyimpannya. Tidak mengeksekusi SQL; handle native ditolak oleh execute_query/query (gunakan execute_sql untuk menjalankan SQL mentah).
query	Kueri tabel atau metrik secara langsung. Mendukung paginasi melalui token lanjutan.
execute_query	Jalankan kueri yang telah dibuat sebelumnya dan kembalikan hasilnya dengan metadata kolom.
execute_sql	Jalankan kueri SQL mentah terhadap database. Memerlukan izin native-query pengguna pada database target. Dapat dinonaktifkan di seluruh instans melalui pengaturan mcp-execute-sql-enabled.
execute_question	Jalankan pertanyaan tersimpan berdasarkan id dan kembalikan baris + metadata kolomnya. Berjalan di bawah izin pemanggil. Pertanyaan berparameter tidak didukung (mengembalikan error).

Tulis

Alat	Deskripsi
create_metric	Simpan kueri sebagai metrik yang dapat digunakan kembali. Menerima query_handle dari construct_query. Kueri memerlukan satu agregasi dan maksimal satu pengelompokan tanggal.
update_metric	Perbarui metrik tersimpan. Semantik patch. Mengatur collection_id akan memindahkannya; mengatur archived: true akan mengarsipkannya — soft delete yang dapat dibalikkan, digunakan saat diminta untuk menghapus metrik. query pengganti harus tetap berupa metrik yang valid.
create_question	Simpan kueri sebagai pertanyaan bernama (kartu). Menerima query_handle dari construct_query (MBQL) atau construct_native_query (SQL native). Menyimpan native memerlukan izin DB native-query.
update_question	Perbarui pertanyaan tersimpan. Semantik patch. Mengatur collection_id akan memindahkan kartu. Mengatur archived: true akan mengarsipkannya — soft delete yang dapat dibalikkan, digunakan saat diminta untuk menghapus pertanyaan. Mengganti kueri menerima handle construct_query atau construct_native_query.
create_dashboard	Buat dasbor baru, secara opsional diisi dengan pertanyaan tersimpan (diposisikan otomatis di grid).
update_dashboard	Perbarui metadata dasbor (nama, deskripsi, koleksi, diarsipkan — soft delete yang dapat dibalikkan, digunakan saat diminta untuk menghapus dasbor).
create_collection	Buat koleksi baru. Secara opsional bersarang di bawah parent_collection_id.

Hasil kueri dibatasi hingga 200 baris per permintaan. Ketika lebih banyak baris tersedia, respons menyertakan continuation_token yang dapat diteruskan kembali untuk mengambil halaman berikutnya.

Respons daftar read_resource dibatasi pada 25 item dengan sinyal truncated / total; telusuri URI spesifik untuk melihat lebih banyak, atau sempurnakan melalui search.

Sumber daya

Server mengekspos sumber daya MCP sehingga klien dapat mengambil konten tambahan berdasarkan URI tanpa memperbesar deskripsi alat.

URI Sumber Daya	Deskripsi
metabase://docs/construct-query.md	Sintaks program untuk construct_query dan query: sumber, operasi, bentuk operator, contoh kerja, jebakan.

Alat read_resource (di atas) menggunakan skema URI terpisah untuk menavigasi entitas Metabase (metabase://question/{id}, metabase://database/{id}/tables, dll.). Kedua ruang nama URI bersifat independen: metabase://docs/... adalah untuk konten referensi statis yang diambil melalui resources/read MCP, sementara metabase://table/... dan sejenisnya adalah URI entitas yang diteruskan ke alat read_resource.

Metode JSON-RPC yang didukung

Metode	Deskripsi
initialize	Inisialisasi koneksi MCP. Mengembalikan kapabilitas server dan ID sesi.
notifications/initialized	Notifikasi klien bahwa inisialisasi selesai.
tools/list	Daftar alat yang tersedia (difilter berdasarkan cakupan token).
tools/call	Panggil alat dengan argumen.
resources/list	Daftar sumber daya yang tersedia (difilter berdasarkan cakupan token).
resources/read	Baca sumber daya berdasarkan URI. Memerlukan sesi yang diinisialisasi.
ping	Ping keepalive.

Permintaan dapat dikirim secara individual atau sebagai batch JSON-RPC. Server merespons dengan JSON atau SSE tergantung pada header Accept.

Arsitektur

Implementasi terdapat dalam file-file ini:

• api.clj - Handler HTTP. Mem-parsing permintaan JSON-RPC, memvalidasi header autentikasi dan sesi, memberlakukan pemeriksaan origin (perlindungan DNS rebinding), dan mengirimkan ke metode yang sesuai. Mendukung format respons JSON dan SSE.

• tools.clj - Pengiriman alat dan pembuatan manifes. Membangun daftar alat dari metadata endpoint Agent API, memeriksa cakupan, dan merutekan panggilan alat melalui permintaan Agent API sintetis.

• resources.clj - Registri dan handler sumber daya MCP. Menyimpan sumber daya dokumentasi (seperti referensi construct_query) yang dikunci berdasarkan URI, dengan kontrol akses berbasis cakupan pada resources/list dan resources/read.

• scope.clj - Logika pencocokan cakupan. Mendukung pencocokan tepat, pola wildcard, dan sentinel ::unrestricted untuk autentikasi berbasis sesi.

Alur permintaan

MCP client
  -> POST /api/metabase-mcp (JSON-RPC)
  -> Origin + session validation
  -> Auth: OAuth bearer token or browser session
  -> Scope check against requested tool
  -> Synthetic request to Agent API endpoint
  -> Response materialized as MCP content
  -> JSON or SSE back to client

Bacaan lebih lanjut

• Dokumentasi pengguna MCP
• Sumber Agent API
• Spesifikasi Model Context Protocol