ModelContextProtocol WebAPI

ASP.NET Core tabanlı Model Context Protocol (MCP) HTTP sunucu implementasyonu — AI modellerinin harici araç ve servislerle entegre olmasını sağlar.

---

📖 İçindekiler

• Proje Hakkında
• MCP Nedir?
• Özellikler
• Teknolojiler & Paketler
• Kimlik Doğrulama Mimarisi
• OAuth 2.0 Akışı
• MCP Yapılandırması
• Kullanım
• Proje Yapısı
• Kaynaklar

---

🎯 Proje Hakkında

ModelContextProtocol.WebAPI, Anthropic tarafından tanımlanan Model Context Protocol (MCP) standardını ASP.NET Core WebAPI üzerinde uygulayan bir örnek/referans projesidir. Resmi ModelContextProtocol.AspNetCore NuGet paketi kullanılarak HTTP tabanlı bir MCP sunucusu inşa eder. Bu sayede Claude gibi AI modelleri, özel araçları (tools) HTTP üzerinden çağırabilir.

---

🧠 MCP Nedir?

Model Context Protocol (MCP), AI uygulamalarının harici veri kaynakları ve araçlarla entegrasyonunu standartlaştırmak için Anthropic tarafından geliştirilen açık bir protokoldür.

AI Modeli (Claude, vb.)
        │
        │  MCP Protokolü (HTTP / SSE)
        ▼
  MCP Sunucusu  ←── bu proje
        │
        ├── Tool 1: Özel İş Mantığı
        ├── Tool 2: Veritabanı Sorgusu
        └── Tool 3: Harici API Çağrısı

MCP ile AI modeliniz:

• Tools — Fonksiyon çağırabilir (POST endpoint benzeri, yan etkiler üretmek için kullanılır)
• Resources — Veri kaynaklarına okuma amaçlı erişebilir
• Prompts — Hazır prompt şablonlarını kullanabilir

---

✨ Özellikler

• ✅ ModelContextProtocol.AspNetCore ile HTTP tabanlı MCP sunucusu
• ✅ [McpServerToolType] / [McpServerTool] attribute'ları ile deklaratif tool tanımı
• ✅ WithToolsFromAssembly() ile otomatik tool keşfi
• ✅ .mcp.json ile Claude Desktop / MCP istemci entegrasyonu
• ✅ Dependency Injection ile servis entegrasyonu
• ✅ Kolay genişletilebilir araç ekleme mimarisi

---

🛠 Teknolojiler & Paketler

Paket	Açıklama
ModelContextProtocol.AspNetCore	HTTP tabanlı MCP sunucu desteği (WebAPI projeleri için)
ModelContextProtocol	Ana paket — hosting ve DI extension'ları
.NET 10 / ASP.NET Core

Not: HTTP sunucu için ModelContextProtocol.AspNetCore gereklidir. Sadece stdio tabanlı bir sunucu istiyorsanız ModelContextProtocol paketi yeterlidir.

NuGet ile kurulum:

dotnet add package ModelContextProtocol.AspNetCore --prerelease

🔐 Kimlik Doğrulama Mimarisi

Bu proje, MCP endpoint'ini korumak için iki katmanlı bir authentication yapısı kullanır:

Scheme	Görev
McpAuthenticationDefaults.AuthenticationScheme	Yetkisiz isteklerde WWW-Authenticate header'ı ile MCP istemcisini OAuth akışına yönlendirir
JwtBearerDefaults.AuthenticationScheme	Gelen Bearer token'ı doğrular

🔄 OAuth 2.0 Akışı

Bu sunucu, MCP istemcileri için tam bir OAuth 2.0 Authorization Code Flow + PKCE akışı uygular:

MCP İstemcisi                          Sunucu
     │                                   │
     │── GET /.well-known/oauth-... ───► │  Metadata discovery
     │◄─ { authorization_endpoint, ... } │
     │                                   │
     │── POST /oauth/register ─────────► │  Dynamic client registration
     │◄─ { client_id }                   │
     │                                   │
     │── GET /oauth/authorize ─────────► │  Login formu göster
     │   (code_challenge, PKCE/S256)     │
     │◄─ HTML Login Form                 │
     │                                   │
     │── POST /oauth/login ────────────► │  Kullanıcı doğrula
     │   (username, password)            │  Authorization code üret
     │◄─ 302 redirect_uri?code=...       │
     │                                   │
     │── POST /oauth/token ────────────► │  PKCE doğrula (SHA256)
     │   (code, code_verifier)           │  JWT üret
     │◄─ { access_token, refresh_token } │
     │                                   │
     │── POST /mcp ────────────────────► │  Bearer token ile MCP isteği
     │   Authorization: Bearer <JWT>     │  RequireAuthorization()
     │◄─ MCP Response                    │

⚙️ MCP Yapılandırması

Claude Desktop ile Entegrasyon

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ModelContextProtocol-WebAPI": {
      "url": "http://localhost:5500/mcp"
    }
  }
}

Claude Desktop, /mcp endpoint'ine erişmek istediğinde sunucu WWW-Authenticate header'ı döner. İstemci otomatik olarak /.well-known/oauth-authorization-server discovery endpoint'ini bulur ve OAuth akışını başlatır.

.mcp.json

{
  "mcpServers": {
    "webapi": {
      "url": "http://localhost:5500/mcp"
    }
  }
}

---

💡 Kullanım

Program.cs Yapısı

HTTP tabanlı MCP sunucusu şu şekilde kurulur:

using ModelContextProtocol.Server;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddMcpServer()
    .WithHttpTransport()
    .WithToolsFromAssembly();

var app = builder.Build();

app.MapMcp(); // /mcp endpoint'ini otomatik olarak map eder

app.Run();

💡 url alanı, app.MapMcp() tarafından oluşturulan endpoint'i gösterir. Default path /mcp'dir.

.mcp.json ile Entegrasyon

Projenin kök dizinindeki .mcp.json dosyası MCP istemcileri için sunucu yapılandırmasını içerir:

{
  "mcpServers": {
    "webapi": {
      "url": "http://localhost:5000/mcp"
    }
  }
}

📁 Proje Yapısı

ModelContextProtocol-WebAPI/
│
├── ModelContextProtocol.WebAPI/        # Ana ASP.NET Core projesi
│   ├── MCP/                          # [McpServerToolType] sınıfları
│   ├── Program.cs                      # AddMcpServer + MapMcp yapılandırması
│   └── appsettings.json               # Uygulama yapılandırması
│
├── .mcp.json                           # MCP istemci URL yapılandırması
├── ModelContextProtocol.slnx          # Visual Studio solution dosyası (.slnx yeni format)

📚 Kaynaklar

• Model Context Protocol Resmi Dokümantasyon
• MCP C# SDK (GitHub)
• ModelContextProtocol.AspNetCore NuGet