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ı. Model artık tanıdık: biri beklenmedik bir araç için Model Context Protocol (MCP) sunucusu yazıyor, Claude Desktop kullanıcıları deniyor ve ardından “X için MCP sunucusu yazmalı mıyım?” soruları geliyor. MCP, kısa sürede deneysel bir entegrasyon fikrinden standart araç bağlama katmanına dönüştü.

Apidog'u bugün deneyin

Ancak MCP sunucuları büyüdükçe test tarafı geride kalıyor. stdio üzerinden JSON-RPC mesajlarını elle göndermek “hello world” için yeterli olabilir; fakat 12 araç, 3 prompt ve kararsız bir upstream API varsa bu yöntem hızlıca kırılgan hale gelir. Bu yazıda MCP sunucularını önce manuel olarak nasıl doğrulayacağınızı, ardından aynı akışı Apidog ile sözleşme testi, mock ve CI regresyon paketine nasıl dönüştüreceğinizi göstereceğiz.

Daha genel bir agent bağlamından geliyorsanız, agents.md kılavuzumuz MCP sunucu sözleşmelerini ekip içinde netleştirmek için iyi bir tamamlayıcıdır.

TL;DR

• MCP, Anthropic’in Model Context Protocol’üdür; stdio veya HTTP üzerinden JSON-RPC 2.0 kullanır.
• Test etmeniz gereken ana çağrılar: initialize, tools/list, tools/call, resources/read, prompts/get.
• Önce manuel doğrulayın: sunucuyu çalıştırın, JSON-RPC istekleri gönderin, yanıt şekillerini kontrol edin.
• Sonra otomatikleştirin: istekleri Apidog’a kaydedin, JSONPath iddiaları ekleyin ve paketi CI’da çalıştırın.
• MCP sunucunuzun çağırdığı upstream API’leri mock’layın; testler hızlı ve deterministik kalsın.
• İstek koleksiyonu, mock sunucusu ve CI çalıştırıcısı için Apidog’u indirin.

MCP iki dakikada nedir?

Model Context Protocol spesifikasyonu, JSON-RPC 2.0 tabanlı küçük bir protokol yüzeyi tanımlar. Bir istemci — örneğin Claude Desktop, Cursor veya kendi agent istemciniz — MCP sunucusunu başlatır, initialize el sıkışmasını yapar ve ardından araç, kaynak veya prompt çağrıları gönderir.

Testlerde en çok karşılaşacağınız çağrılar:

• initialize: Protokol sürümü ve yetenek anlaşması.
• tools/list: Sunucunun sunduğu araçları ve argüman JSON Schema’larını döndürür.
• tools/call: Belirli bir aracı ad ve argümanlarla çağırır.
• resources/list ve resources/read: URI adresli okunabilir içerikleri listeler ve okur.
• prompts/list ve prompts/get: Prompt şablonlarını listeler ve oluşturur.

Aktarım katmanı genellikle iki şekilde olur:

• Yerel sunucular için stdio
• Uzak sunucular için HTTP ve çoğu zaman SSE destekli streaming

Bu nedenle MCP sunucusunu “özel bir AI eklentisi” gibi değil, JSON-RPC tabanlı bir API gibi test etmek gerekir.

Ne test etmelisiniz?

İyi bir MCP test paketi en az şu alanları kapsamalı:

1. Protokol uygunluğu

initialize çağrısı beklenen protocolVersion değerini döndürüyor mu?

Örnek kontrol:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2026-04-01",
    "capabilities": {}
  }
}

Kontrol edin:

• $.result.protocolVersion beklenen sürüm mü?
• $.result.capabilities gerçekten desteklenen özellikleri mi ilan ediyor?

2. Araç şemaları

tools/list çıktısındaki her araç için şunları doğrulayın:

• name var mı?
• description boş değil mi?
• inputSchema geçerli JSON Schema mı?
• Zorunlu alanlar doğru işaretlenmiş mi?

Boş veya belirsiz açıklamalar, LLM istemcilerinde araç seçimini kötü etkiler.

3. Araç davranışı

Her araç için en az şu senaryoları test edin:

• Mutlu yol
• Eksik argüman
• Geçersiz tip
• Upstream API hatası
• Timeout veya boş yanıt

Başarılı araç sonucu örneği:

{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Tokyo için hava durumu: 22°C"
      }
    ]
  }
}

Hatalı araç sonucu örneği:

{
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "city alanı zorunludur"
      }
    ]
  }
}

Önemli nokta: Araç yürütme hataları için JSON-RPC error fırlatmayın. MCP’de araç seviyesindeki hatalar normal sonuç içinde isError: true ile dönmelidir.

4. Kaynak erişimi

resources/list ile dönen URI’lar resources/read ile okunabiliyor mu?

Kontrol edin:

• URI formatı kararlı mı?
• İçerik tipi doğru mu?
• Sayfalama varsa ilk sayfadan sonrası çalışıyor mu?

5. Prompt üretimi

prompts/get çıktısı iyi biçimlendirilmiş messages dizisi dönmeli.

Kontrol edin:

• Değişken ikameleri doğru yerde mi?
• Rol alanları (user, assistant, system) beklenen şekilde mi?
• Boş veya eksik mesaj var mı?

6. Hata modları

Gerçek üretim hataları genellikle burada çıkar:

• Upstream API kapalı
• Rate limit
• Eksik argüman
• Yanlış enum değeri
• İstemci timeout
• Paralel tools/call istekleri

stdio ile manuel test

Önce en basit kurulumla başlayın:

• Bir terminal
• MCP sunucu dosyanız
• MCP Inspector veya ham JSON-RPC

Henüz MCP sunucunuz yoksa, Python veya TypeScript için resmi MCP SDK hızlı başlangıcı ile örnek sunucu oluşturabilirsiniz.

Sunucuyu Inspector ile çalıştırın:

npx @modelcontextprotocol/inspector node your-server.js

Inspector, sunucunuza MCP üzerinden bağlanır ve istek/yanıtları görsel olarak gösterir. İlk doğrulama için şunlara bakın:

• Sunucu başlıyor mu?
• initialize başarılı mı?
• tools/list beklenen araçları döndürüyor mu?
• Araç çağrıları doğru içerik blokları dönüyor mu?

Inspector’da her şey doğru görünüyorsa, aynı akışı ham JSON-RPC ile çalıştırın:

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

Ardından şu istekleri de kaydedin:

• tools/list
• tools/call
• resources/list
• resources/read
• prompts/list
• prompts/get

Bu aşamanın sonunda elinizde 6-12 adet standart istek/yanıt çifti olmalı. Bunlar otomatik test paketinizin temelidir.

Manuelden otomatiğe: Apidog’da MCP test paketi oluşturma

Manuel test bariz hataları yakalar. Ancak “son değişiklik araç 7’nin argüman şemasını bozdu mu?” sorusunu her seferinde elle kontrol etmek istemezsiniz.

Akış şu:

1. Manuel testte kullandığınız JSON-RPC isteklerini kaydedin.
2. Her birini Apidog’da istek olarak oluşturun.
3. Yanıtlar için JSONPath iddiaları ekleyin.
4. Upstream API’leri mock’layın.
5. Paketi CI’da çalıştırın.

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

Apidog’da yeni bir proje oluşturun.

HTTP tabanlı MCP sunucusu kullanıyorsanız base URL’i doğrudan MCP endpoint’inize verin.

stdio tabanlı sunucular için test ortamında ince bir HTTP wrapper kullanın. Bu wrapper HTTP üzerinden JSON-RPC alır, isteği stdio sunucusuna yönlendirir ve yanıtı geri döner.

Bu yaklaşım, HTTP olmayan arka uçları test etmek için anlattığımız 2026’da Postman’sız API testi desenine benzer.

Basit test wrapper fikri:

import express from "express";
import { spawn } from "node:child_process";

const app = express();
app.use(express.json());

app.post("/", (req, res) => {
  const child = spawn("node", ["your-server.js"]);

  child.stdin.write(JSON.stringify(req.body) + "\n");
  child.stdin.end();

  let output = "";

  child.stdout.on("data", chunk => {
    output += chunk.toString();
  });

  child.on("close", () => {
    res.type("application/json").send(output.trim());
  });
});

app.listen(3000, () => {
  console.log("MCP test wrapper listening on :3000");
});

2. Standart JSON-RPC isteklerini kaydedin

Her MCP çağrısını ayrı bir istek olarak kaydedin:

• initialize
• tools/list
• tools/call
• resources/list
• resources/read
• prompts/list
• prompts/get

Örnek tools/call gövdesi:

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

Aynı aracın negatif senaryosunu da ekleyin:

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

3. JSONPath iddiaları ekleyin

Otomasyonun amacı yalnızca isteği göndermek değil, yanıt sözleşmesini doğrulamaktır.

tools/list için temel iddialar:

• $.result.tools mevcut
• $.result.tools.length > 0
• Her araçta name var
• Her araçta description var
• Her araçta inputSchema var

tools/call mutlu yol için:

• $.result.isError false veya alan yok
• $.result.content dizi
• $.result.content[0].type beklenen değer
• $.result.content[0].text boş değil

Negatif senaryo için:

• $.result.isError true
• $.result.content[0].text beklenen hata kalıbıyla eşleşiyor

Tam hata mesajına sıkı bağlı kalmak yerine regex veya kararlı hata kodu kullanmak daha güvenlidir.

4. Upstream API’leri mock’layın

Çoğu MCP sunucusu harici bir API’yi sarar:

• Hava durumu API’si
• GitHub
• Linear
• Notion
• Dahili servisler
• Veritabanı gateway’leri

CI sırasında canlı API çağırmak genellikle kötü fikirdir:

• Rate limit’e takılabilirsiniz.
• Testler yavaşlar.
• Üçüncü taraf kesintileri build’i bozar.
• Test verisi deterministik olmaz.

Apidog’un mock sunucusunda her upstream endpoint için gerçekçi yanıtlar tanımlayın. Test sırasında MCP sunucusunun ortam değişkenlerini mock URL’e yönlendirin.

Örnek:

WEATHER_API_BASE_URL=https://mock.example.apidog.io

Üretimde:

WEATHER_API_BASE_URL=https://api.weather.example.com

Mock yaklaşımını sözleşme-öncelikli API geliştirme yazısında daha ayrıntılı ele alıyoruz.

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

Apidog projenizi CLI çalıştırıcı ile CI’a bağlayın. Amaç, her push ve pull request’te MCP sözleşmesini doğrulamaktır.

Minimal GitHub Actions örneği:

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 }}

Böylece araç şeması, prompt çıktısı veya kaynak erişimi bozulursa hata merge edilmeden yakalanır.

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

Apidog’da pratik bir MCP test planı şu yapıda olabilir:

• 1 adet initialize testi
• 1 adet tools/list testi
• Araç başına 2-4 adet tools/call testi:
  • Mutlu yol
  • Eksik argüman
  • Geçersiz tip
  • Upstream hata
• Kaynak ailesi başına:
  • 1 adet resources/list
  • 1 adet resources/read
• Prompt başına:
  • 1 adet prompts/list
  • 1 adet prompts/get
• En az 1 paralel çağrı testi
• En az 1 timeout veya upstream failure testi

10 araç, 3 kaynak ve 4 prompt içeren bir MCP sunucusunda bu genellikle 50-70 istekten oluşur.

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

initialize çağrısını atlamak

Bazı sunucular araç kayıtlarını initialize sırasında yükler. Doğrudan tools/list çağırırsanız testiniz gerçek istemci davranışını yansıtmaz.

Her paketin ilk adımı initialize olmalı.

Araç hatası yerine protokol hatası dönmek

Eksik argüman gibi araç yürütme hataları için JSON-RPC error dönmeyin.

Yanlış:

{
  "jsonrpc": "2.0",
  "id": 10,
  "error": {
    "code": -32602,
    "message": "city is required"
  }
}

Doğru:

{
  "jsonrpc": "2.0",
  "id": 10,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "city is required"
      }
    ]
  }
}

Protokol hatası bağlantı seviyesinde yorumlanabilir; araç hatası ise modelin okuyup toparlayabileceği bir sonuçtur.

Mock verisini üretimden koparmak

Mock, gerçek API’nin hiç döndürmeyeceği alanları döndürüyorsa testleriniz yeşil görünür ama entegrasyon bozulur.

Her sürümde gerçek yanıtlardan mock fixture’larını güncelleyin.

Streaming’i unutmak

HTTP tabanlı MCP sunucuları araç sonuçlarını SSE üzerinden stream edebilir. Test aracınız SSE’yi işlemeli ve nihai birleşik çıktı üzerinde iddia kurabilmelidir.

Apidog’da ilgili istek için streaming’i etkinleştirin ve dönen içerik üzerinde kontrol yapın.

Eşzamanlılığı test etmemek

MCP istemcileri aynı anda birden fazla tools/call gönderebilir. Sunucunuz paylaşılan state tutuyorsa race condition oluşabilir.

Test paketine paralel çağrı senaryosu ekleyin.

Tam hata metnine bağımlı kalmak

Hata mesajları değişebilir. Bunun yerine şunları kontrol edin:

• isError: true
• Kararlı hata kodu
• Regex ile eşleşen kısa hata kalıbı

Benzer sözleşme hatalarını API platformu sözleşme-öncelikli geliştirme yazısında da ele almıştık.

Gerçek dünya kullanım senaryoları

Bir ekip, şirket içi olay yönetimi API’si için MCP sunucusu geliştirdi. tools/list yanıtındaki şekil iddiaları sayesinde bir hafta içinde üç regresyon yakaladılar. Bu testler olmasa hatalar Claude Desktop kullanan tüm mühendislere aynı anda yansıyacaktı.

Notion için açık kaynak MCP sunucusu yayınlayan bağımsız bir geliştirici, CI sırasında Notion rate limit’lerine takılmamak için Apidog mock’larını kullanıyor. Test paketi her PR’da çalışıyor ve katkıda bulunanların geliştirme için gerçek API erişimine ihtiyacı olmuyor.

14 dahili MCP sunucusu yöneten bir platform ekibi, tüm sözleşmeleri ortak bir Apidog çalışma alanında topladı. Yeni sunucular temel test paketini miras alıyor; reviewer’lar merge öncesinde şema farklarını yan yana görebiliyor.

Başka bir ekip, gözlemlenebilirlik platformu için yazdığı MCP sunucusunda aynı test paketini staging ve production ortamlarına karşı çalıştırıyor. Ortam değişkenleri farklı mock fixture’lara işaret ediyor; testler yeniden yazılmadan iki dağıtım da doğrulanıyor.

Sonuç

MCP sunucuları da API’dir. JSON-RPC kullanırlar, sözleşme döndürürler, upstream servislerle konuşurlar ve istemcileri kırabilecek regresyonlar üretirler.

Pratik yaklaşım:

1. MCP Inspector ile manuel doğrulama yapın.
2. Standart JSON-RPC isteklerini kaydedin.
3. Apidog’da istek koleksiyonu oluşturun.
4. JSONPath iddiaları ekleyin.
5. Upstream API’leri mock’layın.
6. Paketi CI’da çalıştırın.

Kapsamanız gereken altı alan:

• Protokol uygunluğu
• Şema doğruluğu
• Araç davranışı
• Kaynak erişimi
• Prompt üretimi
• Hata modları

Sonraki adım: Apidog’u açın, MCP sunucunuz için bir proje oluşturun, manuel yakaladığınız JSON-RPC gövdelerini ekleyin ve önce tools/list için iddialar yazın. Bir saat içinde sunucunuzun sözleşmesinin yayınlanmaya hazır olup olmadığını görebilirsiniz.

Sıkça Sorulan Sorular

MCP nedir?

MCP, Model Context Protocol’dür. Anthropic’in AI istemcilerinin — örneğin Claude Desktop — harici araçları, kaynakları ve prompt’ları nasıl çağıracağını tanımlayan açık spesifikasyondur. stdio veya streaming destekli HTTP üzerinden JSON-RPC 2.0 kullanır. Tam MCP spesifikasyonu modelcontextprotocol.io adresinde yayınlanmıştır.

MCP sunucusunu HTTP wrapper olmadan test edebilir miyim?

Evet. Resmi MCP Inspector doğrudan stdio ile konuşur ve manuel test için arayüz sağlar. Apidog’da otomatik test için CI sırasında stdio sunucusunu ince bir HTTP wrapper arkasına koyabilirsiniz. Üretim trafiği yine stdio üzerinden akabilir.

MCP sunucumun çağırdığı upstream API’leri nasıl mock’larım?

Apidog projenizde her upstream endpoint’i mock rota olarak tanımlayın. Test ortamında MCP sunucusunun base URL ayarını mock URL’e yönlendirin; runtime’da gerçek production URL’lerini kullanın. Benzer yaklaşımı QA mühendisleri için API test araçları yazısında da ele alıyoruz.

Streaming araç sonuçlarını nasıl test ederim?

HTTP MCP sunucuları, araç sonuçlarını Server-Sent Events (SSE) ile stream edebilir. Apidog’da ilgili istekte SSE desteğini açın ve birleşik stream çıktısı üzerinde iddia oluşturun.

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

Evet. initialize yanıtındaki protocolVersion değerini sabitleyin ve test edin. Sürüm uyuşmazlıkları istemci tarafında sessiz uyumsuzluklara neden olabilir.

MCP sunucumu gerçek Claude Desktop’a karşı test etmeli miyim?

Evet, her sürümden önce en az bir smoke test yapın. Ancak Claude Desktop’ı ana test döngünüz yapmayın; manuel, yavaş ve deterministik değildir. Regresyon için Apidog, son smoke test için Claude Desktop kullanın.

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

Resmi MCP sunucuları deposu, dosya sistemi, GitHub, Slack, Postgres ve birçok araç için referans uygulamalar içerir. Araç tanımlarını incelemek, iyi bir MCP sözleşmesinin nasıl görünmesi gerektiğini anlamanın en hızlı yollarından biridir.