Blog

MCP Sunucu Testi Rehberi: Apidog ile Manuel + Otomatik

Ashley Innocent

Ashley Innocent

11 May 2026

MCP Sunucu Testi Rehberi: Apidog ile Manuel + Otomatik

Bu hafta başında bir “Ableton Live MCP” Show HN gönderisi 118 puana ve 78 yoruma ulaştı. Artık bu model tanıdık: birisi beklenmedik bir araç için bir Model Bağlam Protokolü sunucusu yazdı, Claude Desktop kitlesi bunu sevdi ve ardından “X için bir tane yazmalı mıyım?” gönderileri dalgası geldi. MCP, Anthropic'e özel bir deneyden bir yıldan kısa sürede varsayılan bir aracı entegrasyon katmanına dönüştü.

Bu büyümenin gizlediği şey, araçlarda bir boşluk olmasıdır: kimse MCP sunucularını test etmek için temiz bir yol sunmadı. Hata ayıklayıcı ile stdio üzerinden JSON-RPC'yi elle çalıştırmak "hello-world" için iyi olabilir; ancak sunucunuzda 12 araç, 3 istem ve güvenilmez bir yukarı akış API'si olduğunda dağılır. Bu kılavuz, MCP sunucularını manuel olarak test etmek ve bu testleri Apidog ile otomatikleştirmek için pratik bir rehber sunar, böylece MCP sunucularını diğer tüm API'leri gönderdiğiniz gibi gönderebilirsiniz: bir sözleşme, bir mock ve bir regresyon paketi ile.

Daha genel bir aracı bağlamından geliyorsanız, agents.md kılavuzumuz bununla iyi uyum sağlar; oradaki kurallar MCP sunucu sözleşmelerini ekibinize iletmeyi kolaylaştırır.

Uygulamayı İndir

TL;DR (Çok Uzun; Okumadım)

MCP aslında iki dakikada nedir

Model Bağlam Protokolü spesifikasyonu, küçük bir yüzey alanına sahip bir JSON-RPC 2.0 kablo formatı tanımlar. Bir istemci (Claude Desktop, Cursor, kendi aracınız) bir MCP sunucusu başlatır, bir initialize el sıkışması gerçekleştirir ve ardından çağrılar yapar.

Testlerinizin yüzde 90'ını ayıracağınız beş çağrı:

Aktarım, ya stdio (stdin/stdout üzerinde yeni satırla ayrılmış JSON-RPC çerçeveleri) ya da akış destekli HTTP'dir (genellikle akış için SSE ile POST /). Çoğu yerel sunucu stdio kullanırken, uzak sunucular HTTP kullanır.

Test etmenin neden önemli olduğu: her Claude Desktop kullanıcısı, her Cursor kullanıcısı, MCP desteği ekleyen her IDE sunucunuzu çağıracaktır. tools/list şeklindeki hatalar tüm istemcileri aynı anda bozar. Bir regresyonun maliyeti yüksektir.

Ne test etmelisiniz

Sağlam bir MCP sunucusu test paketi altı boyutu kapsar.

Bu kılavuzun geri kalanı, önce manuel, sonra otomatik olarak bunların her birini anlatır.

Stdio ile manuel test

Mümkün olan en basit kurulumla başlayın: bir terminal, sunucu ikili dosyanız ve MCP denetleyicisi veya el ile ham JSON-RPC.

Henüz bir sunucu oluşturmadıysanız, Python veya TypeScript'teki resmi MCP SDK hızlı başlangıcı ile bir iskelet oluşturun. İki araçlı hava durumu örneği, test etmek için yeterlidir.

Sunucuyu denetleyici modunda çalıştırın:

npx @modelcontextprotocol/inspector node your-server.js

Denetleyici, sunucunuza MCP ile konuşan ve her isteği ve yanıtı gösteren yerel bir web kullanıcı arayüzü başlatır. Bu, sunucunun başladığını, yeteneklerini ilan ettiğini ve tools/list'e yanıt verdiğini doğrulamak için en hızlı yoldur.

Denetleyici görünümü doğru göründüğünde, Apidog için çerçeveleri yakalayabilmek amacıyla aynı akışı ham stdio ile çalıştırın:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-04-01","capabilities":{}}}' | node your-server.js

Stdout'ta bir JSON-RPC yanıtı alacaksınız. İsteği ve yanıtı kaydedin. tools/list, tools/call, resources/list ve diğerleri için tekrarlayın. Bu alıştırmanın sonunda, sunucunuzun kablo düzeyindeki sözleşmesini tanımlayan 6 ila 12 standart istek-yanıt çiftine sahip olacaksınız.

Dikkat edilmesi gereken iki şey.

Birincisi, içerik blokları. Bir araç sonucu content: [{ type: "text", text: "..." }] veya content: [{ type: "image", data: "...", mimeType: "image/png" }] döndürür. Bir yanıtta türleri karıştırmaya izin verilir; istemciler bunları nasıl işledikleri konusunda farklılık gösterir.

İkincisi, hatalar. MCP spesifikasyonu açıktır: araç yürütme hataları, isError: true ile normal bir sonuç ve hatayı açıklayan bir içerik bloğu döndürür. Bir aracın içinden JSON-RPC hata yanıtları atmayın; bu, bir araç düzeyindeki hatayı değil, bir protokol düzeyindeki hatayı gösterir. Birçok istemci, protokol hatalarında bağlantıyı düşürür.

Manuelden otomatike: Apidog'da test paketini oluşturma

Manuel test, bariz hataları ortaya çıkarır. “Son değişikliğim araç 7'nin argüman şemasını bozdu mu?” diye sormaya başladığınızda ve bunu öğrenmek için 12 curl komutu yazmak istemediğinizde otomasyona geçersiniz.

Desen: manuel test sırasında kaydettiğiniz her istek-yanıt çiftini Apidog'a kaydedilmiş bir istek olarak yapıştırın, iddialar ekleyin ve her push işleminde paketi çalıştırın.

1. MCP sunucusu için bir Apidog projesi oluşturun

Apidog'u açın, yeni bir proje oluşturun, temel URL'yi MCP sunucunuzun HTTP uç noktasına (veya stdio köprü URL'sine; aşağıya bakın) ayarlayın. Apidog projeleri hem REST'i hem de JSON-RPC'yi destekler; bir JSON-RPC ortamı oluşturun.

HTTP arayüzü olmayan stdio sunucuları için, bunları test için ince bir HTTP sarmalayıcısının arkasında çalıştırın. Resmi denetleyici bir tane sunar; alternatif olarak, HTTP üzerinden JSON-RPC okuyan ve stdio'ya yönlendiren 30 satırlık bir Node betiği gayet iyi çalışır. Aynı deseni, HTTP olmayan arka uçlar için 2026'da Postman'sız API testi makalesinde kullanıyoruz.

2. Standart istekleri kaydedin

initialize, tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get'in her biri için JSON-RPC gövdesini bir istek olarak kaydedin. Apidog bunları gövde, başlıklar ve beklenen durumla birlikte depolar.

Apidog'un istek gövdesi görünümünde bir tools/call isteği şöyle görünür:

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "city": "Tokyo"
    }
  }
}

3. İddialar ekleyin

Otomasyonun amacı, isteği göndermek değil, yanıtı doğrulamaktır. Apidog, JSONPath iddialarını doğal olarak destekler. tools/list için en azından şunları istersiniz:

Bilinen iyi bir girdi üzerindeki tools/call için şunları istersiniz:

Bilinen kötü bir girdi üzerindeki tools/call için (eksik gerekli argüman) şunları istersiniz:

Apidog bu iddiaları istek başına depolar. Hatalar çalıştırma raporunda gösterilir.

4. Yukarı akış API'lerini mocklayın

Çoğu MCP sunucusu harici bir API'yi sarmalar: hava durumu verileri, GitHub, Linear, dahili bir veritabanı. Her commit işleminde CI çalıştırmalarının canlı API'lere ulaşmasını istemezsiniz. İki neden: maliyet ve kararsızlık.

Apidog'un yerleşik mock sunucusu bunu düzeltir. Her yukarı akış uç noktasını gerçekçi bir JSON gövdesi döndüren bir mock rotası olarak tanımlayın. MCP sunucunuzun yapılandırmasını testler sırasında mock URL'sine ve gerçek çalıştırmalar sırasında üretim ortamına yönlendirin. Mock iş akışını sözleşme-öncelikli API geliştirme makalesinde ayrıntılı olarak ele alıyoruz.

Sonuç: saniyeler içinde çalışan, harici ağ gerektirmeyen ve şema regresyonlarını piyasaya sürülmeden çok önce yakalayan bir test paketi.

5. Paketi CI'da çalıştırın

Apidog projeleri CLI çalıştırıcılara dışa aktarılır. apidog run komutu bir proje kimliği alır, kaydedilen her isteği çalıştırır, iddiaları değerlendirir ve başarısızlık durumunda sıfır olmayan bir kodla çıkar. Bunu GitHub Actions'unuza veya zaten kullandığınız herhangi bir CI sağlayıcısına entegre edin.

Minimal bir iş akışı:

name: MCP server tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - name: Start MCP HTTP wrapper
        run: node test/wrapper.js &
      - name: Run Apidog suite
        run: npx apidog run --project-id $APIDOG_PROJECT --env ci
        env:
          APIDOG_PROJECT: ${{ secrets.APIDOG_PROJECT }}
          APIDOG_TOKEN:   ${{ secrets.APIDOG_TOKEN }}

Her push işlemi tüm MCP sözleşmesini çalıştırır. Araç 7'nin şema regresyonu, ortaya çıkmadan yerleşemez.

İyi test kapsamı nasıl görünür

Apidog'da eksiksiz bir MCP sunucusu test planı tipik olarak şunları içerir:

3 kaynak ve 4 istem içeren 10 araçlı bir sunucu için, paket 50 ila 70 istek gönderir. Apidog, mock sunucusu hazır olduğunda bunu yerel olarak 10 saniyenin altında çalıştırır.

MCP sunucularını test ederken sık yapılan hatalar

En sık gördüğümüz modeller bunlardır.

Gerçek dünya kullanım durumları

Şirketlerinin olay yönetimi API'si için dahili bir MCP sunucusu oluşturan bir ekip, tools/list şekli üzerindeki Apidog iddialarını kullanarak bir hafta içinde üç regresyon yakaladı. Bu test olmasaydı, hatalar Claude Desktop kullanan her mühendise aynı anda dağıtılacaktı.

Notion için açık kaynaklı bir MCP sunucusu yayınlayan bağımsız bir geliştirici, CI sırasında Notion'ın hız sınırlarına takılmadan test paketini çalıştırmak için Apidog mock'larını kullanıyor. Paketleri her PR'da çalışır, 8 saniye sürer ve katkıda bulunanların geliştirme için API erişimine ihtiyaç duymaması için Apidog'un mock fixture'larını depoda önbelleğe alır.

14 dahili MCP sunucusu çalıştıran bir platform ekibi, her sunucunun sözleşmesinin yaşadığı paylaşılan bir Apidog çalışma alanı oluşturdu. Yeni sunucular temel bir test paketi miras alır; incelemeciler birleştirmeden önce şema farklılıklarını yan yana karşılaştırabilirler. Ekip, ilk çeyrekte önlenen iki kesinti bildirdi; her ikisi de şirketteki her Claude Desktop kullanıcısına yeniden adlandırılmış bir argüman gönderecek bir PR üzerindeki tools/list şekil iddiaları tarafından yakalandı.

Dahili bir gözlemlenebilirlik platformu için bir MCP sunucusu oluşturan ikinci bir ekip, aynı paketi hazırlama ve üretim ortamlarına karşı çalıştırmak için Apidog'un ortam değiştiricisini kullanıyor. Her ortam farklı bir mock fixture dosyasına işaret eder, böylece aynı 60 iddia tek bir isteği yeniden yazmadan her iki dağıtımı da doğrular.

Sonuç

MCP bu yıl ana akım haline geldi, ancak test hikayesi hala on yıl önceki REST API testlerinin olduğu yerde: geçici, manuel, kırılgan. Ekosistemin yetişmesini beklemek zorunda değilsiniz. MCP sunucunuzu olduğu gibi bir API olarak ele alın, bir sözleşme tasarlayın, yukarı akışları mock'layın ve CI'da iddiaları çalıştırın.

Beş önemli çıkarım:

Bir sonraki adım: Apidog'u açın, bir proje oluşturun, manuel olarak yakaladığınız istek gövdelerini yapıştırın, tools/list için JSONPath iddiaları ekleyin ve paketi çalıştırın. Sunucunuzun sözleşmesinin gönderilmeye yetecek kadar sağlam olup olmadığını bir saat içinde öğreneceksiniz.

Sıkça Sorulan Sorular (SSS)

MCP nedir?

MCP, Model Bağlam Protokolü, Anthropic'in yapay zeka istemcilerinin (Claude Desktop gibi) harici araçları, kaynakları ve istemleri nasıl çağırdığına dair açık spesifikasyonudur. Stdio veya akış destekli HTTP üzerinden JSON-RPC 2.0'dır. Tam MCP spesifikasyonu modelcontextprotocol.io adresinde yayınlanmıştır.

Bir MCP sunucusunu HTTP sarmalayıcı olmadan test edebilir miyim?

Evet. Resmi MCP denetleyicisi doğrudan stdio ile konuşur ve manuel test için bir kullanıcı arayüzü sunar. Apidog'da otomatik test için, CI sırasında stdio'yu ince bir HTTP sunucusuna sarın; üretim trafiği hala stdio üzerinden gider.

MCP sunucumun çağırdığı yukarı akış API'lerini nasıl mocklarım?

Apidog projenizde her yukarı akış uç noktasını bir mock olarak tanımlayın, testler sırasında MCP sunucusunun yapılandırmasını mock URL'sine yönlendirin ve çalışma zamanında üretim URL'lerine geçin. Aynı deseni QA mühendisleri için API test araçları makalesinde ayrıntılı olarak ele alıyoruz.

Akışlı araç sonuçları ne olacak?

HTTP MCP sunucuları, Sunucu Tarafından Gönderilen Olaylar (SSE) üzerinden araç sonuçlarını akışla gönderir. Apidog, kaydedilen isteklerde SSE'yi destekler; istek ayarlarında açın ve birleştirilmiş akış üzerinde iddia oluşturun.

Protokol sürümünü test etmeli miyim?

Evet. Desteklediğiniz protocolVersion'ı initialize içinde sabitleyin ve buna karşı iddia oluşturun. Uyuşmazlıklar sessiz istemci uyumsuzluğuna neden olur.

MCP sunucumu gerçek Claude Desktop'a karşı test edebilir miyim?

Yapabilirsiniz ve her sürümden önce en az bir kez yapmalısınız. Ancak Claude Desktop'ı test döngünüz olarak kullanmayın; yavaş, manuel ve belirleyici değildir. Regresyon paketi için Apidog'u ve duman testi için Claude Desktop'ı kullanın.

Gerçek MCP sunucu örneklerini nerede görebilirim?

Resmi MCP sunucuları deposu, dosya sistemi, GitHub, Slack, Postgres ve düzinelerce başka araç için referans uygulamalara sahiptir. Araç tanımlarını okuyun; bunlar, iyi bir MCP şeklinin neye benzediğini anlamanın en kolay yoludur.

API Tasarım-Öncelikli Yaklaşımı Apidog'da Uygulayın

API'leri oluşturmanın ve kullanmanın daha kolay yolunu keşfedin

Ücretsiz Kaydolİndir
MCP Sunucu Testi Rehberi: Apidog ile Manuel + Otomatik