MCP Sunucusu Nasıl Kurulur: Python ve TypeScript ile Adım Adım Eğitim (2026)

Claude'un gerçekten çağırdığı bir MCP sunucusunu yaklaşık 15 dakikada kurabilirsiniz. Bunu Node 20 ve Python 3.11 üzerinde ölçtük: stdio üzerinde çalışan ve Claude Desktop tarafından algılanan çalışır bir add aracı ilk seferde 14 dakika, yapıyı bir kez öğrendikten sonra 5 dakikanın altında sürdü. Bu eğitim aynı sunucuyu iki kez kuruyor: bir kez Python ve FastMCP 2.x ile, bir kez TypeScript ve @modelcontextprotocol/sdk 1.x ile, böylece kendi yığınınızı seçip gerçek kodu kopyalayabilirsiniz. Önce mimari ve protokol teorisini istiyorsanız, Model Context Protocol rehberimiz bunu kapsar; burada sadece kuruyoruz.

MCP Sunucusu Hızlı Başlangıç: Ne Kuracaksınız

MCP sunucusu, araçları, verileri ve istem şablonlarını Model Context Protocol üzerinden Claude, Cursor veya VS Code gibi yapay zeka istemcilerine sunan küçük bir programdır. Sunucuyu bir kez yazarsınız ve MCP ile uyumlu her istemci onu çağırabilir. Bu eğitimde iki araçlı bir sunucu kuracaksınız (bir add hesaplayıcısı ve bir fetch_url yardımcısı), yerel olarak stdio üzerinde çalıştıracak, test edecek ve gerçek bir istemciye bağlayacaksınız.

Başlamadan önce ihtiyacınız olan her şey burada.

Her iki yol da aynı şekilde davranan bir sunucu üretir. Ekibinizin zaten kullandığı dili seçin. Tercihiniz yoksa Python ile başlayın, çünkü FastMCP ilk sunucuyu daha kısa yapar.

Bir MCP Sunucusu Gerçekte Neyi Sunar?

Kod yazmadan önce, bir sunucunun sunabileceği üç şeyi bilmek yardımcı olur. Bir MCP sunucusu araçlar (modelin çağırabileceği işlevler, örneğin "veritabanını sorgula"), kaynaklar (modelin yükleyebileceği salt okunur veriler, örneğin bir dosya veya kayıt) ve istemler (yeniden kullanılabilir istem şablonları) sunar. Kuracağınız çoğu sunucu araç ağırlıklı olacaktır; kaynaklar ve istemler isteğe bağlıdır.

MCP sunucusu, tanımı: Model Context Protocol'ü konuşan ve bir yapay zeka istemcisinin çalışma zamanında keşfedip çağırabileceği araç, kaynak ve istem listesini ilan eden bir süreç.

İstemci (örneğin Claude Desktop) ana bilgisayar olarak davranır. Sunucunuzu başlatır veya ona bağlanır, "hangi araçların var?" diye sorar ve ardından model bir aracın yararlı olduğuna karar verdiğinde onları çağırır. Modeli asla sunucunun içinden çağırmazsınız. Akış ters yönde işler.

Bu yön önemlidir. Sunucunuz pasif bir sağlayıcıdır. İstemcinin bağlanmasını bekler, keşif isteğini yanıtlar ve çağrılan aracı çalıştırır. Bu zihinsel modeli aklınızda tutun, eğitimin geri kalanı kendiliğinden yerine oturur.

Python'da MCP Sunucusu Nasıl Kurulur (Adım Adım)

Python, çalışan bir sunucuya giden en hızlı yoldur, çünkü FastMCP protokol tesisatını üstlenir ve sıradan işlevleri bir dekoratörle araçlara dönüştürür. Aşağıdaki her şey resmi Python SDK'sını kullanır. İşte dört adım.

Adım 1: Projeyi kurun. Artık MCP Python projeleri için standart olan uv'yi kullanın:

uv init mcp-demo
cd mcp-demo
uv add "mcp[cli]"

pip'i tercih ederseniz: python -m venv .venv && source .venv/bin/activate && pip install "mcp[cli]".

Adım 2: Sunucuyu yazın. server.py oluşturun:

from mcp.server.fastmcp import FastMCP
import httpx

# Name shows up in the client's tool list
mcp = FastMCP("demo-server")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers and return the sum."""
    return a + b

@mcp.tool()
async def fetch_url(url: str) -> str:
    """Fetch a URL and return the first 2000 characters of the body."""
    async with httpx.AsyncClient(timeout=10) as client:
        resp = await client.get(url)
        return resp.text[:2000]

if __name__ == "__main__":
    mcp.run()  # defaults to stdio transport

Dikkat edilecek iki şey var. Docstring, modelin okuduğu araç açıklaması olur, bu yüzden onu bir talimat gibi yazın. Ve tür ipuçları (a: int) otomatik olarak giriş şeması olur, böylece FastMCP JSON şemasını sizin için üretir.

Adım 3: Çalıştırın. mcp.run() sunucuyu stdio üzerinde başlatır; istemcilerin yerel olarak başlattığı taşıma budur. Geliştirme sırasında bunu doğrudan çalıştırmazsınız; istemci başlatır. Hızlı bir test için geliştirme çalıştırıcısını kullanın:

uv run mcp dev server.py

Adım 4: Temiz çıktı döndürün. Şimdiden belirtmeye değer bir tuzak: bir dize veya tipli bir değer döndürün, render edileceğini umduğunuz iç içe bir sözlük değil. Üretim bölümünde buna geri döneceğiz, ama kısaca belirsiz dönüş türleri bazı istemcilerde sessizce kesilebilir.

Bu tam bir Python MCP sunucusudur. İki araç, gerçek ağ çağrıları, otomatik şema. Sırada aynı şey TypeScript'te.

TypeScript'te MCP Sunucusu Nasıl Kurulur (Adım Adım)

TypeScript yolu resmi TypeScript SDK'sını doğrudan ve giriş doğrulaması için zod'u kullanır. FastMCP'den biraz daha ayrıntılıdır, ancak türler mükemmeldir ve Node ana bilgisayarlarına temiz şekilde dağıtılır.

Adım 1: Projeyi kurun.

mkdir mcp-demo && cd mcp-demo
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx

Adım 2: Sunucuyu yazın. server.ts oluşturun:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "demo-server", version: "1.0.0" });

server.tool(
  "add",
  "Add two numbers and return the sum.",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
  }),
);

server.tool(
  "fetch_url",
  "Fetch a URL and return the first 2000 characters.",
  { url: z.string().url() },
  async ({ url }) => {
    const resp = await fetch(url);
    const body = await resp.text();
    return { content: [{ type: "text", text: body.slice(0, 2000) }] };
  },
);

const transport = new StdioServerTransport();
await server.connect(transport);

Adım 3: Çalıştırın. Geliştirme sırasında: npx tsx server.ts. Üretim için tsc ile derleyin ve oluşturulan .js dosyasını Node ile çalıştırın. Dönüş biçimine dikkat edin: her araç { content: [{ type: "text", text: ... }] } döndürür. Bu açık content dizisi, Python'daki "temiz bir dize döndür" kuralının TypeScript karşılığıdır. SDK ham nesneler değil, tipli içerik blokları ister.

Adım 4: Girişi zod ile doğrulayın. z.string().url() şeması, işleyiciniz çalışmadan önce geçersiz girdiyi reddeder; bir model argümanları üretirken tam da istediğiniz şey budur.

Aynı iki araç, aynı davranış, deyimsel TypeScript. Şimdi istemcilerin sunucunuza nasıl ulaşması gerektiğine karar verelim.

stdio ve Streamable HTTP: Hangi Taşımayı Kullanmalısınız?

MCP sunucuları iki taşımadan biri üzerinden konuşur. stdio, sunucuyu istemcinin başlattığı ve standart giriş/çıkış üzerinden iletişim kurduğu yerel bir alt süreç olarak çalıştırır. Streamable HTTP, sunucuyu istemcilerin HTTP üzerinden bağlandığı bir ağ hizmeti olarak çalıştırır. Sunucunun nerede yaşaması gerektiğine göre seçin.

Pratik kural: stdio üzerinde kurun ve test edin, ancak birden fazla kişi veya makine sunucuya ihtiyaç duyduğunda Streamable HTTP'ye geçin. Çoğu sunucunun stdio'dan asla ayrılması gerekmez. Yukarıdaki mcp.run() ve StdioServerTransport() çağrıları zaten stdio'dur, bu yüzden geliştirme için hazırsınız.

MCP Sunucunuzu Inspector ile Nasıl Test Edersiniz

Sunucunuzu Claude'a bağlamadan önce, onu MCP Inspector ile izole şekilde test edin. Sunucunuza bağlanan, araçlarını listeleyen ve onları elle çağırmanıza izin veren bir tarayıcı arayüzüdür. Sunucunuza karşı çalıştırın:

# Python
npx @modelcontextprotocol/inspector uv run server.py
# TypeScript
npx @modelcontextprotocol/inspector npx tsx server.ts

Inspector, add ve fetch_url araçlarınızı gördüğünüz, bir test çağrısı tetiklediğiniz ve ham yanıtı okuduğunuz yerel bir sayfa açar. Bu, MCP geliştirmesinin en iyi alışkanlığıdır. Bir aracın şeması bozuksa veya bir dönüş değeri yanlışsa, Claude içindeki sessiz bir hataya bakmak yerine bunu burada saniyeler içinde görürsünüz. Böyle, aksi takdirde istemci üzerinden tam bir hata ayıklama turuna mal olacak hatalı bir giriş şemasını yakaladık. Her seferinde önce Inspector'da test edin.

MCP Sunucunuzu Claude Desktop, Claude Code ve Cursor'a Nasıl Bağlarsınız

Inspector memnun olduğunda, gerçek bir istemciyi sunucunuza yönlendirin. Her istemci, sunucunuzu stdio üzerinden nasıl başlatacağını söyleyen bir yapılandırma dosyası okur.

Claude Desktop. claude_desktop_config.json dosyasını düzenleyin (macOS'ta: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "demo-server": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/mcp-demo", "run", "server.py"]
    }
  }
}

Claude Desktop'u yeniden başlatın, araçlarınız bağlayıcılar simgesi altında görünür.

Claude Code. Sunucuyu projenizden tek bir komutla ekleyin: claude mcp add demo-server -- uv run server.py. Claude Code onu proje yapılandırmanızda saklar ve başlangıçta yükler. Claude Code'u betiklemek için kancalar da kullanıyorsanız, Claude Code kancaları rehberimiz özel MCP araçlarıyla iyi gider.

Cursor. Aynı mcpServers bloğunu proje kök dizinindeki .cursor/mcp.json dosyasına ekleyin. Biçim, Claude Desktop'unkiyle eşleşir. Claude Code içinde çalışan bir MCP sunucusunun gerçek bir örneği için, Higgsfield'i Claude Code'a nasıl bağladığımıza bakın.

Her yapılandırmada mutlak yollar kullanın. Göreli yollar, bir sunucunun başlamamasının en yaygın nedenidir.

Bir MCP Sunucusunu Üretime Dağıtma (Kimlik Doğrulama ve Barındırma)

Sunucunuzun paylaşılması gerektiğinde, onu stdio'dan Streamable HTTP'ye taşıyın ve üç şey ekleyin: kimlik doğrulama, hata işleme ve bir ana bilgisayar.

• Kimlik doğrulama. Uzak MCP sunucuları, MCP yetkilendirme spesifikasyonu uyarınca OAuth 2.1 kullanmalıdır. Dahili araçlar için, HTTP uç noktasında bir bearer token kontrolü pratik asgaridir. Asla herkese açık, kimliği doğrulanmamış bir araç sunucusu yayınlamayın, çünkü SQL çalıştıran veya dahili API'lere vuran bir araç aktif bir saldırı yüzeyidir.
• Hata işleme. Araç gövdelerini try/except (veya try/catch) ile sarın ve hata fırlatmak yerine tipli bir hata mesajı döndürün. Model "sorgu başarısız oldu, işte nedeni" ifadesini kesik bir bağlantıdan çok daha iyi yönetir.
• Barındırma. Uzun ömürlü bir Node veya Python süreci çalıştıran her platform işe yarar: küçük bir VPS, Fly.io, Railway veya kendi altyapınızda bir konteyner. Süreci sıcak tutun, çünkü soğuk başlangıçlar ilk araç çağrısına gecikme ekler.
• Eşzamanlılık ve maliyet. Araçlarınız aşağı yönde bir LLM veya ücretli bir API çağırıyorsa, önüne bir ağ geçidi koyun. LLM ağ geçidi araçları derlememiz hız sınırlama ve yedeklemeyi kapsar ve bağlam mühendisliği araçları araç çıktısının modelin bağlam penceresini şişirmesini önlemeye yardımcı olur.

Python için run çağrısını mcp.run(transport="streamable-http") olarak değiştirin; TypeScript için StdioServerTransport'u SDK'nın StreamableHTTPServerTransport'u ile değiştirin. Araç tanımları hiç değişmez. Taşıma soyutlamasının amacı budur.

MCP Sunucularını Üretimde Yayınlarken Öğrendiklerimiz

Techsy'de dahili kullanım için MCP sunucuları kurduk ve bazı dersler ancak gerçek trafik onlara vurduğunda ortaya çıkıyor. İşte ölçtüklerimiz ve nerede ısırıldığımız.

Yayınladığımız ilk sunucu, FastMCP 2.x ile Python mcp 1.x SDK'sı üzerine kurulmuş, daha sonra karşılaştırmak için @modelcontextprotocol/sdk 1.x'te yeniden yazılmış salt okunur bir Postgres sorgu aracıydı. Bir 2026 yığınında (Node 20, Python 3.11), yerel stdio araç çağrıları çağrı başına yaklaşık 8 ila 12 ms taşıma ek yükü ekledi. Aynı sunucuyu bir VPS üzerinde Streamable HTTP'ye taşıdığımızda, çağrı başına maliyet 40 ila 70 ms'ye yükseldi; neredeyse tamamı protokol maliyeti yerine ağ gidiş-dönüşüydü. FastMCP soğuk başlangıcı süreç için yaklaşık 300 ms'ydi, bu yüzden üretim sürecini sıcak tutuyoruz.

Bize yaklaşık iki saate mal olan tuzak: ham bir Python sözlüğü döndüren bir araç Inspector'da iyi render edildi ama Claude Desktop içinde kesik geldi. Dönüş değerini tipli bir metin dizesi olarak sarmak bunu anında düzeltti. Bu yüzden bu eğitim her yerde iç içe nesneler yerine dizeler ve content metin blokları döndürür. Hemen karşılık veren diğer alışkanlık, bir istemci yapılandırmasına dokunmadan önce her sunucuyu npx @modelcontextprotocol/inspector üzerinden geçirmekti; bu, aksi takdirde Cursor'da sessizce başarısız olacak TypeScript yeniden yazımındaki bozuk bir giriş şemasını ortaya çıkardı.

İlk etapta sunuculara hangi araçları kuracağınızı seçiyorsanız, 2026'nın en iyi MCP sunucuları listemiz iyi bir fikir bankasıdır.

Techsy MCP Geliştirmeye Nasıl Yaklaşıyor

Techsy'de MCP sunucularını, müşteriler için yayınladığımız yapay zeka ajan sistemlerinin bir parçası olarak kuruyoruz; ajanları tipli bir araç katmanı üzerinden dahili veritabanlarına, CRM'lere ve API'lere bağlıyoruz. Yaklaşımımız dar başlamak (stdio üzerinde iyi test edilmiş bir araç), onu Inspector'da doğrulamak ve ancak birden fazla ajanın ihtiyaç duyduğunda kimliği doğrulanmış bir HTTP hizmetine yükseltmektir. Ajan mantığı karmaşıklaştığında özel sunucuları Claude Agent SDK ile birleştiriyoruz.

İşte dürüst versiyon: çoğu ekip ilk sunucusunu aşırı kuruyor. İlk gün nadiren HTTP, OAuth ve bir düzine araca ihtiyacınız olur. Bir MCP entegrasyonuna ikinci bir göz isterseniz, ücretsiz danışmanlık alın, size bunun tek araçlı bir stdio işi mi yoksa gerçekten altyapı gerektiren bir şey mi olduğunu söyleyelim.

Sıkça Sorulan Sorular

MCP sunucumu Python'da mı yoksa TypeScript'te mi kurmalıyım?

Ekibinizin zaten kullandığı dili kullanın. FastMCP ile Python, ilk çalışan sunucuya giden en kısa yoldur, çünkü bir dekoratör bir işlevi araca dönüştürür. Resmi SDK ile TypeScript biraz daha ayrıntılıdır ama size mükemmel türler verir ve Node ana bilgisayarlarına temiz şekilde dağıtılır. Her ikisi de istemci için aynı davranan sunucular üretir.

MCP sunucusu kurmak için FastMCP gibi bir çerçeveye ihtiyacım var mı?

Hayır, ama yardımcı olur. FastMCP, resmi Python mcp SDK'sının içinde gelir ve protokol şablon kodunun çoğunu kaldırır. İnce taneli kontrol için daha düşük seviyeli Server API'sini kullanabilirsiniz, ancak neredeyse her sunucu için FastMCP (Python) veya McpServer (TypeScript) doğru araçtır ve çok daha az koddur.

Çalışmayan bir MCP sunucusunu nasıl hata ayıklarım?

Önce MCP Inspector üzerinden geçirin: npx @modelcontextprotocol/inspector ardından çalıştırma komutunuz. Inspector araçlarınızı listeler ve onları doğrudan çağırmanıza izin verir, böylece istemciyi suçlamadan önce sunucunun çalıştığını doğrulayabilirsiniz. Inspector sorunsuzsa ama istemci değilse, yapılandırmanızın mutlak yollar kullandığını ve istemciyi yeniden başlattığınızı kontrol edin.

FastMCP, MCP'nin resmi bir parçası mı?

Evet. FastMCP, resmi Model Context Protocol Python SDK'sıyla üst düzey sunucu arayüzü olarak paketlenmiştir. Kullandığınız @mcp.tool() dekoratörü, Python sunucuları kurmanın önerilen yoludur, üçüncü taraf bir eklenti değil.

Yerel ve uzak MCP sunucusu arasındaki fark nedir?

Yerel bir sunucu, istemci tarafından alt süreç olarak başlatılarak makinenizde stdio üzerinde çalışır; kişisel araçlar ve geliştirme için idealdir. Uzak bir sunucu, Streamable HTTP üzerinde web hizmeti olarak çalışır ve birden fazla istemci tarafından erişilebilir; bu, OAuth 2.1 kimlik doğrulaması gerektirir. Önce yerel kurun, yalnızca paylaşırken uzağa geçin.

MCP sunucusunu hangi dillerde kurabilirim?

Model Context Protocol'ün Python, TypeScript, Java, Kotlin ve C# için resmi SDK'ları, başka dillerde topluluk SDK'ları vardır. MCP bir tel protokolü olduğundan, stdio veya HTTP üzerinden JSON-RPC okuyup yazabilen her dil bir sunucu uygulayabilir, ancak resmi SDK'lar sizi bu işten kurtarır.

MCP sunucusu ChatGPT ve Gemini ile çalışır mı yoksa sadece Claude ile mi?

MCP, ChatGPT, Gemini, Cursor ve VS Code Copilot dahil tüm ajan tabanlı yapay zeka ekosisteminde benimsenen açık bir standarttır. Kurduğunuz tek bir sunucu, uyumlu her istemciyle çalışır. Model başına ayrı bir entegrasyon yazmazsınız; protokolün tüm amacı budur.

Çalışan bir MCP sunucusu kurmak ne kadar sürer?

stdio üzerinde bir veya iki araçlı ilk sunucu, çalışma ortamınız kurulduktan sonra yaklaşık 15 dakika sürer. Node 20 üzerinde ilk kez kuran biri için 14 dakika, tekrarlı bir kurulum için 5 dakikanın altında ölçtük. Kimlik doğrulama, HTTP taşıması ve üretim barındırması gerçek zaman alan şeylerdir, sunucunun kendisi değil.