MCP Tümleştirmesi

MCP nedir?

MCP (Model Context Protocol), yapay zekâ istemcilerinin dış araçları çağırmasını sağlar. DBX MCP, yapay zekâ asistanınıza DBX'te yapılandırılmış veritabanı bağlantılarına erişim verir.

Yapay zekâ agent'ı → DBX MCP → veritabanınız → sonuçlar
                                 ↘ DBX masaüstü uygulaması (açma ya da sonuç gösterme)

Hızlı Başlangıç

npm install -g @dbx-app/mcp-server

{
  "mcpServers": {
    "dbx": {
      "command": "npx",
      "args": ["-y", "@dbx-app/mcp-server"]
    }
  }
}

Desteklenen Yapay Zekâ Agent'ları

DeepSeek Harness

DeepSeek Harness, MCP sunucularını bir mcpServers JSON nesnesi yerine Cordis eklenti girdileriyle yükler. @dbx-app/mcp-server kurulduktan sonra web profili için aşağıdaki girdiyi $DSH_HOME/profiles/web/cordis.patch.yml dosyasına ekleyin: DSH_HOME ayarlanmamışsa varsayılan olarak ~/.dsh kullanılır.

- insert:
    - id: mcp-dbx
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: dbx
        transport: stdio
        command: dbx-mcp-server

Üst düzeydeki - insert: sarmalayıcısını koruyun ve diğer patch girdilerinin üzerine yazmayın. Başka bir DSH profili için yoldaki web yerine o profilin adını yazın. dbx-mcp-server komutu, DSH işleminin PATH değişkeninde bulunmalıdır; gerektiğinde tam çalıştırılabilir yolu kullanın.

Oluşan yapılandırmayı doğrulamak için dsh web --dump-config çalıştırın, ardından DSH'yi yeniden başlatın ya da sıcak yeniden yüklemesinin patch'i uygulamasını bekleyin. Araçlar modele mcp__dbx__<araç> biçiminde sunulur. Araç adlarının ve yetki kurallarının kararlı kalması için serverName: dbx değerini değiştirmeyin. Bağlantı erişimi ve yürütme modu DBX Ayarlar → MCP bölümünden yönetilmeye devam eder.

Araçlar

DBX MCP şu anda 17 araç sunar:

Bağlantı kapsamlı oturumlar; bağlantıyı değiştiren ve masaüstü arayüzü araçlarını gizler.

Durumlu Sorgu Oturumları

Normal dbx_execute_query çağrıları birbirinden bağımsızdır. Bir iş akışının veritabanı oturum durumunu koruması gerektiğinde önce dbx_open_session çağırın ve döndürülen sessionId değerini sonraki dbx_execute_query çağrılarına geçirin. Tipik kullanımlar:

• USE ya da veritabanı bağlamı değişiklikleri
• Geçici tablolar
• Oturum değişkenleri ve ayarları
• Tek bir bağlantı gerektiren açık işlemler ya da çok adımlı tanılamalar

Oturumlar yalnızca SQL bağlantılarını destekler ve tek bir bağlantı ile veritabanına bağlıdır. Bilinmeyen, kapatılmış ya da süresi dolmuş kimlikler sessizce sıradan bir sorguya dönmek yerine hata verir. İşiniz bittiğinde dbx_close_session çağırın. Boşta kalan oturumlar 30 dakika sonra geri alınır ve sunucu en fazla 32 eşzamanlı oturuma izin verir.

Veritabanı Erişimi

DBX Masaüstü için yerel Streamable HTTP

Masaüstü isteğe bağlı olarak kendi Streamable HTTP MCP uç noktasını barındırabilir. Varsayılan olarak kapalıdır ve Ayarlar → MCP → HTTP Servisi bölümünden etkinleştirildiğinde varsayılan olarak yalnızca 127.0.0.1:5225/mcp üzerinde dinler. Masaüstü işlemi dinleyiciyi yönetir, yerel bir bearer belirteci oluşturur, kopyalanabilir bir istemci yapılandırması gösterir ve yönetilen HTTP servisi beklenmedik biçimde sonlanırsa yeniden başlatır.

Yerel bir MCP istemcisini bağlamak için:

1. Ayarlar → MCP → HTTP Servisi bölümünü açın, Streamable HTTP Servisi'ni açın ve başka bir aygıtın gerçekten erişmesi gerekmedikçe varsayılan loopback adresini koruyun.
2. Kaydet ve servisi başlat'a tıklayın. Değişen bir adresi, portu ya da yolu kaydetmek, servisi yeniden başlatarak yapılandırmayı uygular.
3. Gösterilen servis adresini ve bearer belirtecini MCP istemcisine kopyalayın.

Üretilen değerleri HTTP destekleyen bir MCP istemcisinde kullanın. Taşımaya özgü alan adları istemciler arasında değişir, ancak temel yapılandırma şudur:

{
  "type": "http",
  "url": "http://127.0.0.1:5225/mcp",
  "headers": {
    "Authorization": "Bearer <DBX Masaüstü'nün gösterdiği belirteç>"
  }
}

Yerel istemciler için varsayılan loopback bağlamasını koruyun. Bir yerel ağ adresine bağlanmak, Uzaktan erişime izin ver seçeneğini açmayı ve izin verilen tam Host yetkilerini belirlemeyi gerektirir; tarayıcı istemcileri ayrıca tam Origin değerlerine ihtiyaç duyar. İstemci varsayılan olmayan bir port gönderdiğinde izin verilen Host değerinde sunucu:port kullanın. Belirteci değiştirmek, önceki kimlik bilgisini hemen geçersiz kılar.

Yerel bağlantılar

MCP, DBX'te kayıtlı bağlantıları kullanır. Yerel olarak çalışan bağlantılar Masaüstü uygulamasının açık kalmasını gerektirmez; köprü destekli ya da kurulu Agent/sürücü yolları yine kendi çalışma zamanlarına bağlıdır.

Yaygın yerel yollar:

DBX_DATA_DIR değerini dbx.db dosyasını içeren dizine ayarlayın. Dosyanın kendisine ayarlamayın.

Yerel SQL, tek düğümlü Redis ve MongoDB yolları MCP üzerinden doğrudan çalışabilir. SSH, küme, üreticiye özgü, dış sürücü ve Agent/JDBC kullanılabilirliği; bağlantı yapılandırmasına ve kurulu DBX bileşenlerine bağlıdır. DBX ürününün desteklediği her veritabanının bağımsız MCP ikili dosyasına gömülü olduğunu varsaymayın.

DuckDB, bağımsız DBX DuckDB sürücüsünü kullanır. Yerel MCP üzerinden bir DuckDB bağlantısını sorgulamadan önce sürücüyü DBX Sürücü Yöneticisi'nden kurun. MCP ikili dosyası yardımcı bileşen istemcisini içerir, ancak DuckDB motorunu gömmez.

Agent/JDBC veritabanları

Oracle, KingbaseES ve XuguDB kendi yerel DBX Agent'larını gerektirir, JRE gerektirmez. Dameng, DB2, Hive, Trino, Snowflake, SAP HANA ve diğer JDBC Agent bağlantıları; uygun Agent'ı, JDBC sürücüsünü ve JRE'yi gerektirir. MCP kullanmadan önce gereken bileşeni DBX'te kurun.

DBX Web ve Docker modu

Yerel bağlantılar yerine dağıtılmış bir DBX Web arka ucunu kullanmak için DBX_WEB_URL değişkenini ayarlayın. Web girişi korumalıysa DBX_WEB_PASSWORD değerini de aynı giriş parolasına ayarlayın.

DBX Web istekleri standart sistem proxy ortam değişkenlerine uyar: https URL'leri için HTTPS_PROXY/https_proxy, http URL'leri için HTTP_PROXY/http_proxy, yedek olarak ALL_PROXY/all_proxy ve atlama listesi olarak NO_PROXY/no_proxy (virgülle ayrılmış sunucular, örn. localhost,127.0.0.1,.internal.example). Boş ya da ayarlanmamış bir proxy değeri doğrudan bağlantı (proxy yok) anlamına gelir. HTTP, HTTPS ve SOCKS5 proxy'leri desteklenir (http://127.0.0.1:7890 ya da socks5://127.0.0.1:1080); kimlik doğrulama gerektiren proxy'ler standart kullanıcı:parola@sunucu:port URL biçimini kullanır, örn. http://admin:admin123@127.0.0.1:7890. Her DBX Web isteğine ek başlıklar eklemek için (örneğin bir ağ geçidinin önünde belirteç kimlik doğrulaması) DBX_WEB_HEADERS değerini başlık adları ve dize değerlerinden oluşan bir JSON nesnesine ayarlayın, örn. {"Authorization":"Bearer <token>"}. Kendinden imzalı HTTPS arka uçlarında sertifika doğrulaması varsayılan olarak açıktır; doğrulamayı kapatmak için DBX_WEB_INSECURE_SKIP_VERIFY=1 ayarlayın ya da özel bir CA'ya güvenmek için DBX_WEB_CA_CERT değerini bir PEM/DER CA dosyasına ayarlayın. Aynı değişkenler Web modundaki DBX CLI tarafından da kullanılır.

DBX Web ve Docker aynı bağımsız DuckDB sürücüsünü gerektirir. İlk açılıştan sonra Sürücü Yöneticisi'nden kurun. Docker, kurulu sürücüleri /app/data/agents altında saklar; bu yüzden /app/data bir birim olarak bağlandığında korunurlar.

DBX Web için yerel Streamable HTTP

DBX Web de MCP'yi kendisi barındırabilir. Bu mod, DBX_WEB_MCP_TOKEN (ya da DBX_WEB_MCP_TOKEN_FILE) yapılandırılmadıkça kapalıdır. Mevcut Web dinleyicisini ve /mcp yolunu kullanır, bu yüzden Docker ve ters proxy dağıtımlarının ikinci bir açık porta ihtiyacı olmaz. DBX_WEB_MCP_ALLOWED_HOSTS değerini, istemcilerin Host başlığında gönderdiği herkese açık yetkilerle (uygun olduğunda eşlenen portla birlikte) yapılandırın. Bir Compose dosyasına gerçek bir belirteç yazmak yerine DBX_WEB_MCP_TOKEN_FILE ya da dağıtım gizli bilgi yöneticinizi kullanın.

Örneğin 4225:4224 olarak yayımlanan bir kapsayıcı http://localhost:4225/mcp adresini kullanır:

environment:
  DBX_WEB_MCP_TOKEN: replace-with-a-long-random-secret
  DBX_WEB_MCP_ALLOWED_HOSTS: localhost:4225
ports:
  - "4225:4224"

İstemciler Authorization: Bearer <DBX_WEB_MCP_TOKEN> göndermelidir. Tarayıcı tabanlı istemciler ayrıca tam kaynaklarıyla DBX_WEB_MCP_ALLOWED_ORIGINS gerektirir, örneğin https://mcp.example.com; yerel istemciler normalde Origin başlığı göndermez. Bir ters proxy herkese açık bir yol öneki eklediğinde DBX_PUBLIC_BASE_PATH=/dbx ayarlayın; yerel uç nokta o zaman /dbx/mcp olur. Yerel HTTP ile mevcut DBX_WEB_URL stdio bağdaştırıcısı birlikte var olabilir: DBX bağlantılarını ve MCP politikasını paylaşırlar, bağdaştırıcı ise yalnızca stdio destekleyen istemciler için kullanışlı kalır.

Masaüstü arayüz araçları

dbx_open_table ve dbx_execute_and_show, DBX masaüstü uygulamasını gerektirir ve Web modunda ya da kapsamlı politika arayüz araçlarını gizlediğinde kullanılamaz. Diğer araçların Masaüstü'ne ihtiyaç duyup duymadığı, bağlantının yerel yürütmeyi mi yoksa bir köprü/Agent yolunu mu kullandığına bağlıdır.

Güvenlik ve Ortam Değişkenleri

DBX, Ayarlar → MCP altında tek bir yetkili MCP politikası saklar ve her istekte yeniden yükler:

WHERE TRUE, WHERE 1 = 1, _id: {$exists: true} gibi etkisiz bir koşul ya da belirsiz bir MongoDB filtresi yüksek riskli olmayı sürdürür. Bağlantı düzeyindeki salt okunur koruma, üretim koruması, veritabanı kimlik bilgileri ve MCP bağlantı izin listesi her modda üst sınır olarak kalır.

MCP'ye açılan bağlantılar için Ayarlar → MCP varsayılan bir yürütme yetkisi belirleyebilir: genel moddan devralma, salt okunur, güvenli yazma ya da yüksek riskli yazma. Seçili veritabanları kullanıldığında tek tek veritabanları kendi yürütme yetkisini alabilir. Yürütme yetkileri en özel kapsamdan geriye doğru düşer: veritabanı ayarı → bağlantı varsayılanı → genel varsayılan. Örneğin genel ve bağlantı varsayılanları veri okuma/yazma iken bir veritabanı tam erişim kullanabilir. Bağlantı düzeyindeki salt okunur koruma, üretim koruması, veritabanı kapsamı ve veritabanı kimlik bilgileri; hiçbir veritabanı ayarının atlayamayacağı bağımsız kesin sınırlar olarak kalır.

Aynı sayfa yalnızca seçili MCP araçlarını da sunabilir. Bu, yalnızca istemci tarafında bir görüntüleme tercihi değil, her çağrıda uygulanan bir kuraldır; eski bir araç listesini saklayan bir istemci, sunucu tarafındaki izin listesi değiştiğinde reddedilir.

Erişimi sırayla yapılandırın

Geçerli kapsamı bu sırayla tanımlamak için Ayarlar → MCP bölümünü kullanın:

1. MCP'nin tüm bağlantıları (ileride eklenecekler dâhil) mi yoksa yalnızca belirtilen bağlantıları mı görebileceğini seçin.
2. Açılan her bağlantı için tüm veritabanları, belirtilen veritabanları ya da erişim yok seçin. Belirtilen veritabanı adları tam eşleşmedir; şu anda izin verilen adları bulmak için dbx_list_databases kullanın, ardından isterseniz bu veritabanları için yürütme yetkileri belirleyin.
3. Her bağlantının varsayılan yürütme yetkisini belirleyin. Tüm veritabanları açıldığında her veritabanı için, seçili veritabanlarında ise geçersiz kılınmayanlar için geçerlidir.
4. Yalnızca istemcinin ihtiyaç duyduğu MCP araçlarını seçin, ardından genel varsayılan yürütme yetkisini belirleyin.

En özel yürütme ayarı kazanır, ancak izin verilen bir araç yine de gizlenmiş bir bağlantıyı, veritabanı kapsamını, bağlantının salt okunur durumunu, üretim korumasını ya da veritabanı hesabının kendi yetkilerini atlayamaz. Seçili kapsamın dışındaki bir veritabanı için yapılan istekler DATABASE_OUT_OF_SCOPE ile reddedilir. Veritabanına özgü yürütme yetkileri varken, bu sınırların atlanmasını önlemek için veritabanları arası SQL ve MongoDB toplama yazmaları reddedilir.

Yükseltme sırasında, yürütme politikası sürümü olmayan kayıtlı bağlantı kuralları önceki üst sınır anlamını korur ve genel yetkiyi genişletemez. Yalnızca geçerli Ayarlar arayüzüyle kaydedilen bir kural, kapsamlı geçersiz kılma anlamı için işaretlenir; mevcut bir eski kuralı düzenlemek, yeni davranışı etkinleştirmeden önce geçerli üst sınırını taşır.

Güncel sunucular; DBX_MCP_ALLOW_WRITES ya da DBX_MCP_ALLOW_DANGEROUS_SQL değişkenlerinin DBX politikasını genişletmesine izin vermez. Yükseltme uyumluluğu için DBX_MCP_ALLOW_WRITES=0 (ya da false), merkezî bir politika ilk kez kaydedilene dek MCP'yi salt okunur tutar. Ondan sonra merkezî politika yetkilidir ve eski yetki değişkenleri yok sayılır. Eski bağlantı kapsamı değişkenleri DBX izin listesini yalnızca daraltabilir.

Sorun Giderme

Gereksinimler

• Node.js 18.18.0 ya da üstü
• En az bir bağlantı yapılandırılmış bir DBX kurulumu
• Agent/JDBC bağlantıları için uygun DBX Agent, JDBC sürücüsü ve JRE
• İki arayüz aracı kullanılırken çalışan DBX masaüstü uygulaması