Metabase

Metabase MCP Sunucusu

Metabase, yapay zeka istemcilerinin doğrudan bir Metabase örneğine bağlanmasını sağlayan yerleşik bir Model Context Protocol (MCP) sunucusu içerir. https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http kullanır ve Metabase'in Agent API'si üzerine inşa edilerek arama, gezinme, sorgulama, görselleştirme ve içerik oluşturma/güncelleme araçlarını sunar - tümü bağlanan kullanıcının izinlerine göre kapsamlandırılır.

Uç Nokta

MCP sunucusu şu adreste mevcuttur:

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

Eski /api/mcp yolu, mevcut istemciler için bir takma ad olarak hâlâ çalışır, ancak /api/metabase-mcp duyurulacak kurallı URL'dir.

İstemci bağlama

Herhangi bir MCP uyumlu istemciyi /api/metabase-mcp uç noktasına yönlendirin. Örneğin, Claude Code ile:

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

Claude Desktop için, aynı URL'yi kullanarak bir özel bağlayıcı oluşturun.

Cursor için, Ayarlar > MCP bölümünü açın ve türü streamable-http olarak ayarlanmış ve URL'si aşağıdaki gibi olan yeni bir sunucu ekleyin:

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

Kimlik doğrulama

MCP istemcileri OAuth 2.0 ile kimlik doğrular. Metabase kendi gömülü OAuth sunucusunu çalıştırır - harici bir sağlayıcı gerekmez.

İlk bağlantı için akış:

1. İstemci, Metabase'in OAuth uç noktalarını keşfeder.
2. İstemci kendini Metabase'e kaydeder.
3. Kullanıcı, oturum açmak ve bağlantıyı onaylamak için Metabase'e yönlendirilir.
4. İstemci, kullanıcının Metabase izinleriyle kapsamlandırılmış bir erişim belirteci alır.

Tarayıcı tabanlı oturumlar (çerez kimlik doğrulaması), API anahtarları ve mb:full belirteçleri MCP kapsamına sahip değildir, bu nedenle bağlanabilirler ancak kapsamlı hiçbir aracı çağıramazlar.

Kapsamlar

Erişim belirteçleri, bir istemcinin kullanabileceği araçları sınırlamak için kapsamlandırılır:

Kapsam	Sağladığı araçlar
agent:content:read	browse_collection, browse_data, get_content, get_parameter_values, glossary, learn, search ve catalog://metabase/fields veri kaynağı (bkz. Kaynaklar)
agent:content:write	bookmark_content, collection_write, dashboard_write, document_write, duplicate_content, measure_write, metric_write, question_write, segment_write
agent:delivery:write	alert_write, subscription_write
agent:query:run	execute_query, refresh_ui_credential, render_drill_through, run_saved_question, visualize_query
agent:sql:run	execute_sql

Bir araç yalnızca tablodaki tam kapsamla eşleşir. * veya agent:* gibi bir joker karakter ve ::unrestricted sentinel değeri MCP kapsamı değildir, bu nedenle hiçbir araç vermezler.

Bu kapsamlar yalnızca MCP yüzeyini sınırlar. Hiçbir REST uç noktası bunlardan birini :scope olarak bildiremez, bu nedenle bir MCP istemcisine verilen yeni bir belirteç REST API'sinde hiçbir şey vermez.

Korumalı kaynak meta verilerinin scopes_supported ve 401 zorluğunun scope değeri tablodaki her kapsamı listeler, bu nedenle yeni bir bağlantı hepsini ister. Bazı istemciler 403'ten sonra adım atmaz: Claude'un bağlayıcı ayarlarından manuel yeniden bağlantı, yeni bir istemci kaydeder ve bu listelerin tam olarak neyi listelediğini sorar. Yalnızca temel seviyeyi listelediklerinde, bu yeniden bağlantı hiçbir zaman yazma, ham SQL veya teslimat sunmadı ve kullanıcının bunları verme yolu yoktu (ENG-11089). Yetkilendirme sunucusu meta verileri de hepsini duyurur.

Temel seviye (agent:content:read agent:query:run) onay ekranında kilitlidir: bir istemci bunlardan birini istediğinde, kullanıcı işaretini kaldıramaz. agent:query:run temel seviyededir, böylece grafiklerin asla adım atması gerekmez. Claude Desktop, MCP Apps desteğini bildirmeyen bir oturum üzerinden adım atma sonrasında bir aracı yeniden dener, bu nedenle adım atılmış bir visualize_query reddedilir ve grafiği asla gömülmez.

Belirtecin kapsamına sahip olmadığı bir araç çağrısı veya veri kaynağı okuması, HTTP 403 ve WWW-Authenticate: Bearer error="insufficient_scope" zorluğu ile reddedilir; bu zorluğun scope değeri, belirtecin zaten sahip olduğu v2 kapsamlarını artı gerekeni listeler, böylece bir istemci adım atabilir. Her araç ayrıca kapsamını securitySchemes içinde bildirir; bu, ChatGPT tarafından desteklenen taslak SEP-1488 belirtimidir. MCP 2025-03-26'nın (bu sunucunun bildirdiği sürüm) veya nihai 2026-07-28 araç belirtiminin parçası değildir, bu nedenle diğer istemciler eksik kapsamı 403'ten keşfeder. Bir JSON-RPC toplu işlemi içinde reddetme, bant içi -32600 hatasıdır. UI kabuğu okumaları asla zorlanmaz: bkz. Kaynaklar.

OAuth korumalı kaynak meta verileri şu adreste mevcuttur:

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

Onay ekranında, istemcinin istediği her kapsam işaretli başlar ve temel kapsamlar da kilitlidir. Yalnızca işaretli bırakılan kapsamlar verilir ve yalnızca bu yetkilendirmenin ürettiği belirteç için. Bir işaret kaldırma, uygulamanın zaten sahip olduğu bir belirteci asla etkilemez. İşaretsiz bırakılan bir kapsam Metabase tarafından hatırlanmaz. Daha sonraki bir 403, bunu destekleyen istemcilerde başka bir adım atmayı tetikleyebilir. Diğer istemciler manuel yeniden yetkilendirme gerektirebilir. Her zorluğun error_description değeri, kullanıcının onay ekranında izni vermesi gerektiğine dair bir notla biter.

Bazı istemciler 403'ün error_description değerini kendi metinleriyle değiştirir, bu nedenle initialize sonucunun instructions değerleri kapsam hatalarını modele de açıklar: bir kimlik doğrulama hatası genellikle süresi dolmuş bir oturum açmadan ziyade eksik bir izin anlamına gelir, model başarısız aracı veya kaynağı ve gerektirdiği izni adlandırmalıdır ve kullanıcı yeniden bağlanarak ve izni onay ekranında işaretli bırakarak bunu verir. Talimatlar statik bir dizedir, her çağıran için aynıdır: bağlantı başına izin listesi yoktur.

Grup başına araç erişimi

ai_controls özelliğine sahip Enterprise örneklerinde, bir yönetici yüzeyi izin grupları başına Admin > AI > Kullanım kontrolleri > MCP araç erişimi bölümünden daraltabilir (MCP sunucusu açık olduğunda, bir LLM sağlayıcısı olsun veya olmasın gösterilir). Her grubun mcp_group_permission içinde, üyelerinin hiç bağlanıp bağlanamayacağını ve araç adı başına yöneticinin açık "yes" veya "no" değerini söyleyen bir satırı vardır; girişi olmayan bir araç, yazarının bildirdiği varsayılanı alır, bu nedenle her deftool zorunlu bir :default-access değeri taşır: :allowed veya :denied ve daha sonra yayınlanan bir araç, bir yönetici onu geçersiz kılana kadar her grupta tam olarak bu varsayılanı alır. Girişler araç adına göre anahtarlanır, bu nedenle bir aracı yeniden adlandırmak, eski adlarıyla :renamed-from gerektirir (eski bir ad altında saklanan bir giriş hâlâ geçerlidir ve yönetici API'si onu geçerli ad altında sunar) veya yazar, yöneticinin onun için yaptığı her seçimin atılmasını kabul eder; metabase.mcp.v2.tool-names-test canlı adları sabitler, böylece ikisi de kazara olmaz. Bir kullanıcının etkili politikası, satırı MCP'yi etkinleştiren gruplarının her birinin tool_access değeridir: böyle bir grup varsa MCP açıktır ve bu gruplardan herhangi biri bir aracı evet olarak çözümlerse araç izinlidir. Satırlar tek başına karar verir ve ayrıca izin modunu kaydeder: basit mod (Yöneticiler, Tüm Kullanıcılar ve Tüm kiracı kullanıcıları) veya grup düzeyi mod (diğer her grup); bu, Tüm Kullanıcılar'ın satırının olmadığı durumdur. Bir anahtar, yeni modun gizlediği grupların satırlarını siler ve girişte etkinleştirdiği, satırı olmayan grupları tohumlar (grup düzeyi moda girerken Veri Analistleri, çıkarken Tüm Kullanıcılar ve Tüm kiracı kullanıcıları) ve PUT geçerli modun gizlediği bir grubu reddeder, böylece hiçbir istek önbelleğe alınmış bir modu okumaz. Politika, tools/list ve tools/call içindeki OAuth kapsamlarının üzerine uygulanır (v2/registry.clj) ve grupları erişim vermeyen bir kullanıcı, initialize ve resources/read adreslerinde (MCP kapatılmadan önce açılan oturumlar için) düzeltmeyi adlandıran bir hatayla reddedilir. Yalnızca uygulama araçları (_meta {:ui {:visibility ["app"]}}, yani refresh_ui_credential) yönetici sayfasında değildir: politika herhangi bir MCP Apps aracına izin verirken bunlara izin verilir. Süper kullanıcılar ve dahili çağıranlar asla daraltılmaz; OSS her şeye izin verir. Enterprise'da saklanan satırlar ai_controls özelliği olmadan bile uygulanır (süresi dolmuş veya doğrulanamayan bir belirteç, yöneticinin yapılandırdığı kısıtlamaları korur); özellik yalnızca yönetici sayfasını ve API'sini kapılar. Çözümleyici permissions.clj (defenterprise, EE uygulaması metabase-enterprise.mcp.permissions içinde) ve yönetici API'si /api/ee/ai-controls/mcp-permissions içindedir.

Kullanılabilir araçlar

v2 kayıt defterinden oluşturuldu (deftool). Burada adlandırılan kapsam, kayıt defterinin araç çalışmadan önce kontrol ettiği şeydir; bazı işleyiciler, çağrının ne yaptığını öğrendiklerinde daha fazla kapsam kontrol eder - bir kaynak yerel SQL'e çözümlendiğinde agent:sql:run (question_write) ve bir uyarının veya aboneliğin ertelediği yürütme için agent:query:run (alert_write, subscription_write). Bu reddetmeler aynı 403 insufficient_scope zorluğunu taşır. tools/list, belirtecin ne tuttuğuna bakılmaksızın her aracı gösterir ve kapsamı eksik olan bir belirteç onu çağıramaz.

Araç	Kapsam	Açıklama
alert_write	agent:delivery:write	Bir uyarı oluşturun veya güncelleyin: kaydedilmiş bir sorunun sonuçları bir koşulu karşıladığında bir zamanlamayla gönderilen bir bildirim.
bookmark_content	agent:content:write	Çağıran kullanıcı için içerikte yer imi ekleyin veya kaldırın — Metabase kenar çubuğunun gösterdiği yıldızlı/sık kullanılanlar listesiyle aynı.
browse_collection	agent:content:read	Koleksiyonlara yapısal olarak göz atın — her bölüm üzerinde tek bir birleşik kimlik: sayısal bir kimlik, 21 karakterli bir entity_id, "root" (ad alanı başına yeniden köklendirilir) veya "trash" (arşivlenmiş içerik, yalnızca öğe modu).
browse_data	agent:content:read	Veri hiyerarşisine göz atın: veritabanları → şemalar → tablolar → alanlar.
collection_write	agent:content:write	Bir koleksiyon oluşturun, yeniden adlandırın, taşıyın, arşivleyin veya geri yükleyin — soruları, panoları, modelleri ve belgeleri tutan klasörler.
dashboard_write	agent:content:write	Bir pano oluşturun veya güncelleyin ve düzenini sıralı işlemlerle düzenleyin.
document_write	agent:content:write	Bir belge oluşturun veya güncelleyin.
duplicate_content	agent:content:write	Bir soruyu, panoyu veya belgeyi bir koleksiyona kopyalayın — orijinali okuyup yeniden oluşturmaktan daha ucuz ve daha güvenlidir ve okuma projeksiyonlarının dışında bıraktığı her şeyi korur.
execute_query	agent:query:run	Verilerden bir soruyu yanıtlamanın varsayılan yolu: yapılandırılmış bir (MBQL) sorguyu doğrulayın ve çalıştırın, satırları ve bir query_handle döndürün.
execute_sql	agent:sql:run	Kaçış yolu: bir veritabanına karşı ham bir SQL dizesi çalıştırın, satırları ve bir query_handle döndürün.
get_content	agent:content:read	İçeriği {type, id} ile getirin — arama veya browse_collection yoluyla bulunan her şey için yazılmış okuma.
get_parameter_values	agent:content:read	Bir pano veya kaydedilmiş soru üzerindeki bir filtre için geçerli değerleri getirin, böylece tahmin etmek yerine gerçek değerlerle filtreleyebilirsiniz.
glossary	agent:content:read	Bu Metabase örneğinin tanımladığı şekliyle bir iş terimini arayın; tanımlanan terim adları aracın kendi açıklamasında yer alır.
learn	agent:content:read	Şemaların tam olarak tanımlayamadığı yazım lehçeleri için bu sunucunun görev belgelerini (becerilerini) okuyun.
measure_write	agent:content:write	Bir ölçü oluşturun veya güncelleyin: bir tabloya eklenen, başka bir sorgunun toplama işleminde ["measure", id] olarak başvurulan adlandırılmış, yeniden kullanılabilir bir MBQL toplaması.
metric_write	agent:content:write	Bir metrik oluşturun veya güncelleyin: bir koleksiyonda yaşayan, kendi başına sorgulanabilen veya diğer sorgulardan başvurulabilen kaydedilmiş, yeniden kullanılabilir bir toplama.
question_write	agent:content:write	Kaydedilmiş bir soru veya model oluşturun, güncelleyin veya arşivleyin.
refresh_ui_credential	agent:query:run	Bir Metabase MCP Uygulaması tarafından kullanılan kapsamlı kimlik bilgisini yenileyin.
render_drill_through	agent:query:run	Kullanıcının az önce gezinerek girdiği detaya inme görselleştirmesini oluşturun.
run_saved_question	agent:query:run	Kaydedilmiş bir soruyu (kart) sayısal kimlik veya entity_id ile çalıştırın, satırları satır içi döndürün.
search	agent:content:read	Metabase örneği genelinde içeriği alaka düzeyine göre bulun.
segment_write	agent:content:write	Bir segment oluşturun veya güncelleyin: bir tabloya eklenen, diğer sorguların filtrelerinden başvurulan adlandırılmış, yeniden kullanılabilir bir MBQL filtresi.
subscription_write	agent:delivery:write	Bir pano aboneliği oluşturun veya güncelleyin — tüm bir panonun zamanlanmış teslimatı, örn.
visualize_query	agent:query:run	Bir sorguyu etkileşimli bir grafik veya tablo olarak görselleştirin, konuşmada satır içi oluşturulur.

execute_query çağrı başına row_limit satır döndürür (varsayılan 100, maksimum 2000) — sonuç üzerinde bir sınır değil, bir sayfa boyutu. Kesilmiş bir sayfa truncated: true raporlar ve sorgu toplam bir sıraya sahip olduğunda, bir sonraki sayfa için cursor olarak geri geçirilecek bir next_cursor sağlar; truncated: false ile bir sayfa gelene kadar. Yalnızca ilk N satırını isteyen bir sorgu, aşamasında limit: N taşır (bir order-by ile); sunucu bu sınırı sayfalar arasında harcar, böylece son sayfa imleç olmadan eksiksiz gelir ve sayfalama kendi kendine sona erer.

Kaynaklar

Sunucu, araç açıklamalarını şişirmeden istemcilerin URI ile ek içerik getirebilmesi için MCP kaynaklarını kullanıma sunar.

Kaynak URI	Kapsam	Açıklama
ui://metabase/visualize-query.html	agent:query:run (yalnızca UI kimlik bilgisi)	MCP Uygulamaları iframe kabuğu visualize_query yetenekli bir istemciyi işaret eder.
ui://metabase/render-drill-through.html	agent:query:run (yalnızca UI kimlik bilgisi)	render_drill_through işaret ettiği kabuk.
catalog://metabase/fields	agent:content:read	Her içerik türünün fields bağımsız değişkenlerinde kabul ettiği nokta yolları.

Her kaynak, belirtecin kapsamları ne olursa olsun listelenir. Alanlar kataloğu gibi bir veri kaynağı, yalnızca kapsamını elinde tutan bir belirteç tarafından okunur; aksi takdirde okuma, Kapsamlar altında açıklanan 403 insufficient_scope zorluğunu alır. Bir UI kabuğu herhangi bir belirteç tarafından okunur, çünkü bir MCP Uygulamaları ana bilgisayarı, araç çağrısının yanında bir aracın kabuğunu okur ve bu okuma reddedilirse, ana bilgisayar araç çağrısının 403'ünden sonra devreye girmez. Kabuklar veri taşımaz. Kabuğun kapsamı olmayan bir belirteç tarafından okunan bir kabuk asla bir UI kimlik bilgisi üretmez. Grafik verileri, araç çağrısı ve iframe'in herhangi bir şeyi sorgulamadan önce ihtiyaç duyduğu refresh_ui_credential (her ikisi de agent:query:run) tarafından korunur. Bilinmeyen bir URI, -32602 "Kaynak bulunamadı" hatasıdır.

Beceri paketleri, kaynaklar yerine learn aracı aracılığıyla teslim edilir.

Varlık gezinmesi, bir URI şeması yerine get_content ve browse_* araçlarıyla yapılır; yukarıdaki ui:// kaynakları yalnızca bir iframe oluşturabilen bir istemcinin bağlayacak bir şeyi olması için vardır.

Desteklenen JSON-RPC yöntemleri

Yöntem	Açıklama
initialize	MCP bağlantısını başlatın. Sunucu yeteneklerini ve bir oturum kimliğini döndürür.
notifications/initialized	Başlatmanın tamamlandığına dair istemci bildirimi.
tools/list	Belirtecin kapsamları ne olursa olsun kullanılabilir araçları listeleyin.
tools/call	Bağımsız değişkenlerle bir aracı çağırın.
resources/list	Belirtecin kapsamları ne olursa olsun kullanılabilir kaynakları listeleyin.
resources/read	Bir kaynağı URI ile okuyun; bir veri kaynağı kendi kapsamını gerektirir. Bir oturum gerektirir.
ping	Canlı tutma ping'i.

İstekler tek tek veya bir JSON-RPC toplu işi olarak gönderilebilir. Sunucu, Accept başlığına bağlı olarak JSON veya SSE ile yanıt verir.

Mimari

Uygulama şu dosyalarda yaşar:

• transport.clj - HTTP taşıması. JSON-RPC isteklerini ayrıştırır, kimlik doğrulamayı ve oturum başlıklarını doğrular, kaynak denetimlerini (DNS yeniden bağlama koruması) uygular ve uygun yönteme dağıtır. Hem JSON hem de SSE yanıt biçimlerini destekler.

• v2/api.clj - Araç yüzeyi işleyicisi. Taşımayı v2 araç + kaynak kayıtlarına bağlar ve yöntem dağıtımını tanımlar (tools/list, tools/call, resources/list, resources/read, ping).

• v2/registry.clj - v2 araç kayıt defteri. Araçlar deftool aracılığıyla kendi kendine kaydolur; kayıt defteri kapsamları kontrol eder, bağımsız değişkenleri doğrular, çağrıları dağıtır ve kullanımı kaydeder.

• scope.clj - Kapsam eşleştirme mantığı. Yalnızca tam eşleşmeler: joker karakterler, nil kapsamları ve ::unrestricted sentinel hiçbir şeyle eşleşmez.

İstek akışı

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

Daha fazla okuma

• MCP kullanıcı belgeleri
• Aracı API kaynağı
• Model Context Protocol belirtimi