AI Ajanlarıyla Mimari Diyagram Nasıl Oluşturulur (MCP)

AI asistanları bir açıklamayı diyagrama dönüştürmede başarılıdır. Sorun ertesi gün başlar. Bir sohbette PNG olarak ya da bir pull request'te Mermaid kod parçası olarak duran bir diyagram, yalnızca bir kopyadır. Kopyayı kimse güncellemez ve bir ay sonra anlattığı sistemle çelişir.

Model Context Protocol (MCP), ajanın çalıştığı yeri değiştirir. MCP üzerinden Archboard'a bağlanan bir ajan, size bir görsel vermek yerine ekibinizin tarayıcıda açtığı yapılandırılmış diyagramın kendisini okur ve düzenler. Değişiklikleri tuvalde canlı olarak belirir ve adına çalıştığı kişinin adıyla etiketlenir; o kişi bu değişiklikleri tek adımda geri alabilir.

Bu rehber, bir AI uygulamasını Archboard'a nasıl bağlayacağınızı gösteriyor, ilk taslaktan incelemeye kadar uygulamalı bir örnek üzerinden ilerliyor ve pratikte önemli olan prompt'ları, izinleri ve sınırları ele alıyor.

Bir ajan Archboard'la neler yapabilir

Archboard diyagramları, düğüm paketlerinden gelen tipli düğümlerden oluşur: bir Kubernetes Deployment'ı, bir bulut veritabanı, bir C4 konteyneri ya da bir BPMN görevi, üzerinde etiket olan bir kutu değil, port'ları ve özellikleri olan bir düğümdür. MCP üzerinden bir ajan şunları yapabilir:

• Erişebildiği diyagramları bir özet (çerçeveler, sayılar, üzerinde kimin çalıştığı) ya da eksiksiz düğüm ve kenar kayıtları olarak listelemek ve okumak.
• Bir açıklamadan, bir işlem listesinden ya da gerçek düğüm tiplerine eşlenen bir Mermaid akış şemasından diyagram oluşturmak.
• Tek bir değişiklik olarak uygulanan bir işlem grubuyla diyagramı düzenlemek: düğüm eklemek, port'ları bağlamak, taşımak, stilini değiştirmek ya da kaldırmak.
• Bir PNG anlık görüntüsü render ederek işini kontrol etmek ve MCP Apps destekleyen uygulamalarda diyagramı sohbetin içinde göstermek.
• Kendi değişikliklerinden birini geri almak.

Archboard'un kendi AI modeli yoktur. Ajanı siz getirirsiniz: Claude, Cursor, VS Code ya da OAuth ile giriş yapılan uzak bir MCP sunucusu ekleyebilen başka bir uygulama. AI ajanları sayfasında kısa bir genel bakış var.

AI uygulamanızı bağlayın

Archboard'un MCP sunucusu https://getarchboard.app/mcp adresindedir. Streamable HTTP ve OAuth kullanır; bu yüzden kopyalamanız gereken bir API anahtarı yoktur. Uygulamanız bağlanırken Archboard giriş sayfasını açar; Google ya da GitHub ile giriş yapar ve uygulamanın istediği erişimi onaylarsınız.

Onay ekranında uygulamanın hangi organizasyonları ve çalışma alanlarını kullanabileceğini ve her birinde neler yapabileceğini seçersiniz: okuma, düzenleme ya da silme (diyagramları çöp kutusuna taşıma). Daha sonra Ayarlar > Bağlı uygulamalar bölümünden uygulamayı yeniden adlandırabilir, neleri kullanıp neler yapabileceğini değiştirebilir ya da erişimini kaldırabilirsiniz.

Yaygın birkaç uygulamada kurulum:

Claude (web ve masaüstü). Customize > Connectors'ı açın, Add custom connector'ı seçin ve https://getarchboard.app/mcp adresini girin. Team ve Enterprise planlarında önce bir Owner bağlayıcıyı Organization settings > Connectors altında ekler; ardından siz Customize > Connectors üzerinden bağlanırsınız.

Claude Code.

claude mcp add --transport http archboard https://getarchboard.app/mcp

Ardından giriş yapmak için bir oturumda /mcp komutunu çalıştırın.

Cursor. Sunucuyu ~/.cursor/mcp.json dosyasına ekleyin:

{
  "mcpServers": {
    "archboard": { "url": "https://getarchboard.app/mcp" }
  }
}

VS Code. Sunucuyu mcp.json dosyanıza ekleyin (VS Code servers anahtarını kullanır):

{
  "servers": {
    "archboard": { "type": "http", "url": "https://getarchboard.app/mcp" }
  }
}

Diğer uygulamalar. Planınız izin veriyorsa https://getarchboard.app/mcp adresini uygulamanın bağlayıcı ya da MCP ayarlarında uzak MCP sunucusu olarak ekleyin. Uygulamanın, istemci gizli anahtarı (client secret) gerektirmeyen OAuth ile girişi desteklemesi gerekir; istemci geliştiricileri için ayrıntılar MCP belgelerinde.

Uygulamalı örnek: taslaktan incelemeye bir online mağaza

Aşağıda Archboard'a bağlı bir ajanla yapılmış bir oturum var. Prompt'lar sizin de yazacağınız türden; parantez içindeki araç adları ise ajanın arka planda çağırdığı araçlar.

1. İlk taslağı isteyin

Online mağazamız için bir C4 konteyner diyagramı çiz: bir web uygulaması, bir API, sipariş e-postalarını e-posta sağlayıcımız üzerinden gönderen bir arka plan worker'ı, bir PostgreSQL veritabanı ve ödemeler için Stripe. Kendi çalıştırdığımız her şeyi bir sistem sınırının içine koy.

Ajan bir çalışma alanı seçer (list_workspaces), ihtiyaç duyduğu C4 düğüm tiplerini arar (search_node_types) ve diyagramı oluşturur (create_diagram). Ardından hiçbir şeyin üst üste binmediğini ve her kenarın etiketli olduğunu kontrol etmek için bir anlık görüntü render eder (render_snapshot) ve sonucu sohbette gösterir (show_diagram).

Taslak bir başlangıç noktasıdır. Ajan konteynerleri sizin cümlenizden seçti; siz söylemedikçe worker'ın veritabanından da okuduğunu bilemez.

2. Sözle düzenleyin, tuvalde inceleyin

Worker siparişleri veritabanından da okuyor. API ile PostgreSQL arasına bir Redis önbelleği ekle ve her bağlantıyı protokolüyle etiketle.

Ajan mevcut diyagramı okur (get_canvas) ve tek bir işlem grubu uygular (apply_ops). Diyagram sizde açıksa, yeni düğümlerin uygulamanın ve sizin adınızla etiketlenmiş bir imlecin yanında belirdiğini görürsünüz. Diyagramı açık tutan ekip arkadaşlarınız da aynı şeyi görür.

İlk iki prompt'tan sonra diyagram şöyle görünüyor:

3. Beğenmediğinizi geri alın

Son değişikliği geri al.

Ajanın her değişikliği tek bir adımdır. Ajan kendi değişikliğini geri çevirebilir (revert_change) ya da siz, değişiklikten hemen sonra editörde beliren geri alma bildiriminden onu tek adımda geri alabilirsiniz. Bu arada başka birinin değiştirdiği alanlar korunur.

4. Mevcut bir diyagram hakkında soru sorun

Hangi konteynerler PostgreSQL ile konuşuyor ve hangi protokolle?

Böyle bir soruda ajan yalnızca okur (get_canvas). Mevcut bir diyagramı yeni bir ekip arkadaşına anlatmak, bir ajanın yaptığı en faydalı işlerden biridir ve hiç yazma erişimi gerektirmez.

İyi çalışan prompt'lar

• Diyagramın türünü söyleyin. "C4 konteyner diyagramı", "her namespace için bir çerçeve olan Kubernetes diyagramı", "her ekip için bir şeridi olan BPMN süreci". Ajan böylece genel kutular yerine uygun düğüm paketini kullanır.
• Her sınırın içine neyin gireceğini belirtin. Çerçeveler, namespace'ler ve VPC'ler anlam taşır; bu yüzden ajana neyin nereye gideceğini söyleyin.
• Etiketli kenarlar isteyin. "Her bağlantıyı protokol ve port ile etiketle" demek, okları belgeye dönüştürür.
• Her değişikliği küçük tutun. Değişiklik başına tek bir istek, her şeyi baştan yazdırmaktan daha kolay incelenir ve geri alınır.
• Ajandan işini kontrol etmesini isteyin. "Bir anlık görüntü render et ve üst üste binenleri düzelt" demek, yerleşim sorunlarını siz bakmadan yakalar.
• Bir özet isteyin. "Neleri değiştirdiğini listele" demek, size pull request ya da ekip sohbeti için hazır bir inceleme notu verir.

Kim neyi kontrol eder

Bir AI uygulamasını ekibinizin üzerinde çalıştığı diyagramlara bağlamak haklı sorular doğurur. Archboard'un uyguladığı kurallar şunlar:

• Kapsamı siz seçersiniz. Bir uygulama yalnızca izin verdiğiniz organizasyonları ve çalışma alanlarını görür ve oralarda yalnızca izin verdiğiniz şeyi yapar: okuma, düzenleme ya da silme. Gerçekte neler yapabileceğini; bu ayar, ona verilen scope'lar, rolünüz ve planınız arasından en kısıtlayıcı olanı belirler.
• Değişiklikler görünür ve kime ait oldukları bellidir. Bir ajanın imleci ve değişiklikleri, hem tuvalde hem sürüm geçmişinde uygulamanın ve adına çalıştığı kişinin adıyla etiketlenir.
• Geri alma tek adımdır. Ajanınızın bir değişikliğini editördeki geri alma bildiriminden geri alabilir ya da 7 gün içinde ajandan onu geri çevirmesini isteyebilirsiniz. Organizasyon sahipleri ve yöneticileri de geri alabilir.
• Silinen geri getirilebilir. Bir ajanın bir diyagramı çöp kutusuna taşıyabilmesi için silme izni gerekir ve Archboard ajanlara bunu yalnızca siz istediğinizde yapmalarını söyler. Diyagramı Çöp kutusu'ndan geri yükleyebilirsiniz.
• Diyagramdaki metin veridir. Archboard ajanlara, bir diyagramdaki etiketleri, notları ve adları asla talimat olarak değil, veri olarak ele almalarını ve görselleri yalnızca siz istediğinizde eklemelerini söyler.

Ne zaman ajan, ne zaman elle çizim

Ajanlar ilk taslaklarda, tekrarlayan düzenlemelerde ("her orders-* servisini checkout-* olarak yeniden adlandır"), zaten yapmakta olduğunuz bir değişiklikle diyagramı uyumlu tutmada ve başkasının çizdiği bir diyagramı açıklamada iyidir. Bir servisi az önce değiştiren bir kodlama ajanı, mimari diyagramı aynı oturumda güncelleyebilir.

Neyin önemli olduğuna karar vermek için elle çizmek hâlâ daha iyidir. Bir diyagram, bir sistem hakkında ortaya konan bir argümandır ve neyi dışarıda bırakacağınızı seçmek bir muhakeme meselesidir. Yazma işini ajana bırakın, muhakemeyi kendinizde tutun.

Bilmeniz gereken sınırlar

• Plan sınırları geçerlidir. MCP her planda editörle aynı plan sınırlarıyla çalışır. Free planda bu, 3 diyagram ve diyagram başına 15 diyagram düğümü artı 150 not, metin, çıkartma ve zihin haritası konusu demektir.
• Araç çağrılarında dakika başına hız sınırı vardır. Bir ajan sınıra ulaştığında Archboard, yeniden denemeden önce ne kadar beklemesi gerektiğini ona söyler.
• Ajan yalnızca sizin söylediklerinizi ve diyagramda olanı bilir. Archboard üzerinden çalışan cluster'ınızı ya da kod tabanınızı göremez. Bir bağımlılık önemliyse bunu söyleyin ya da kodu bir kodlama ajanına okutun.

SSS

Hangi AI uygulamaları Archboard'a bağlanabilir? OAuth ile giriş yapılan uzak bir MCP sunucusu ekleyebilen ve istemci gizli anahtarı (client secret) gerektirmeyen uygulamalar. AI ajanları sayfasında Claude, Cursor, VS Code, Claude Code ve diğerleri için hızlı kurulum var.

Archboard kendi AI modelini mi kullanıyor? Hayır. Archboard diyagram çalışma alanıdır; akıl yürütmeyi bağladığınız AI uygulaması yapar.

Ajan tüm diyagramlarımı görebilir mi? Yalnızca bağlarken izin verdiğiniz organizasyonları ve çalışma alanlarını, her biri için seçtiğiniz izinle görebilir. Varsayılan olarak, sonradan katılacaklarınız da dahil hepsine silme izniyle erişir; bunu onay ekranında ya da daha sonra Ayarlar > Bağlı uygulamalar'da daraltabilirsiniz.

Ajanın yaptığını geri alabilir miyim? Evet. Ajanın her değişikliği, editördeki geri alma bildiriminden geri alabileceğiniz tek bir adımdır; uygulama da son 7 gün içindeki kendi değişikliklerini geri çevirebilir.

Free planda çalışır mı? Evet. MCP her planda, editörle aynı plan sınırlarıyla çalışır.

Ücretsiz başlayın — tek kullanıcı, kredi kartı gerekmez.