API to MCP Gateway

English | Türkçe

---

<a name="english"></a>

English

API to MCP Gateway is a modern, open-source platform that acts as a bridge between standard REST/OpenAPI Web APIs and the Model Context Protocol (MCP). It dynamically converts REST endpoints into MCP tools, enabling LLM clients (such as Cursor, Claude Desktop, or n8n) to seamlessly and safely interact with your APIs through a unified interface.

Built entirely using a modern and high-performance stack (TypeScript + Next.js App Router), this project provides a unified architecture for API management, OpenAPI spec ingestion, secure credential encryption, and MCP server hosting.

Key Features

• 🔌 Dynamic OpenAPI Parsing: Upload OpenAPI/Swagger specification files or fetch them from a URL to instantly register endpoints.
• 🛠️ Auto-Tool Extraction: Automatically map REST endpoints into standard MCP tools.
• 🔒 Secure Credential Storage: Encrypt target API headers, tokens, and keys at rest using military-grade AES-256-CBC encryption.
• 🛡️ SSRF Protection: Built-in security guard preventing Server-Side Request Forgery when importing remote schemas.
• 🚀 Dual MCP Transport: Exposes both an HTTP MCP endpoint (ideal for web/cloud integrations like n8n) and a stdio MCP process (perfect for local clients like Claude Desktop).
• 💻 Elegant Dashboard: Manage integrations, credentials, endpoints, and tools via a fully responsive Web UI.

---

System Architecture

graph TD
    %% Subgraph 1: Clients
    subgraph Clients ["<font size=4 color='#3b82f6'>■ Clients / LLM Hosts</font>"]
        Claude["<b>Claude Desktop</b><br/><i>(stdio)</i>"]
        Cursor["<b>Cursor / IDE</b><br/><i>(HTTP)</i>"]
        n8n["<b>n8n Workflows</b><br/><i>(HTTP)</i>"]
        Admin["<b>Developer / Admin</b><br/><i>(Web Browser)</i>"]
    end

    %% Subgraph 2: Gateway
    subgraph Gateway ["<font size=4 color='#10b981'>■ API to MCP Gateway (Next.js)</font>"]
        STDIO["<b>stdio Entry</b><br/><i>mcp/stdio.ts</i>"]
        HTTP_EP["<b>HTTP MCP Route</b><br/><i>api/mcp/route.ts</i>"]
        UI["<b>Dashboard UI</b><br/><i>app/(dashboard)</i>"]
        
        ServerCore["<b>MCP Server Core</b><br/><i>lib/mcp/server.ts</i>"]
        Parser["<b>Spec Parser</b><br/><i>lib/server/spec-parser.ts</i>"]
        Proxy["<b>API Proxy</b><br/><i>lib/mcp/api-proxy.ts</i>"]
        Crypto["<b>Crypto Service</b><br/><i>lib/server/crypto.ts</i>"]
    end

    %% Subgraph 3: Storage
    subgraph Storage ["<font size=4 color='#a78bfa'>■ Database / Data Layer</font>"]
        Prisma["<b>Prisma ORM</b><br/><i>lib/db.ts</i>"]
        DB[("<b>PostgreSQL DB</b>")]
    end

    %% Subgraph 4: External Services
    subgraph External ["<font size=4 color='#f59e0b'>■ Target Services / External APIs</font>"]
        ExtAPI["<b>External Web APIs</b><br/><i>(Target Endpoints)</i>"]
    end

    %% Connections
    %% Clients to Entrypoints
    Claude ==> STDIO
    Cursor ==> HTTP_EP
    n8n ==> HTTP_EP
    Admin ==> UI

    %% Entrypoints to Core / Actions
    STDIO --> ServerCore
    HTTP_EP --> ServerCore
    
    %% UI & Parser Flow
    UI --> Parser
    Parser --> Prisma
    
    %% Core DB loading
    ServerCore --> Prisma
    Prisma --> DB
    
    %% Execution Flow
    ServerCore --> Proxy
    Proxy <--> Crypto
    Proxy ==> ExtAPI

    %% Styling Nodes
    classDef clientNode fill:#1e2937,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef gatewayNode fill:#1f2937,stroke:#10b981,stroke-width:2px,color:#fff;
    classDef dbNode fill:#1e1b4b,stroke:#a78bfa,stroke-width:2px,color:#fff;
    classDef extNode fill:#78350f,stroke:#f59e0b,stroke-width:2px,color:#fff;

    class Claude,Cursor,n8n,Admin clientNode;
    class STDIO,HTTP_EP,UI,ServerCore,Parser,Proxy,Crypto gatewayNode;
    class Prisma,DB dbNode;
    class ExtAPI extNode;

    %% Subgraph Styling
    style Clients fill:#111827,stroke:#3b82f6,stroke-width:2px;
    style Gateway fill:#0b0f19,stroke:#10b981,stroke-width:2px;
    style Storage fill:#11101b,stroke:#a78bfa,stroke-width:2px;
    style External fill:#14110b,stroke:#f59e0b,stroke-width:2px;

How the System Works

1. Management & Config: Developers define integrations, upload OpenAPI schemas, and register authentication credentials securely via the Web Dashboard.
2. Database Ingestion: Schemas are parsed and stored as structured endpoints in the PostgreSQL database using Prisma ORM.
3. MCP Hosting: The gateway listens for requests on both HTTP and stdio channels.
4. Proxy & Security: When an LLM executes a tool, the Gateway loads the endpoint configuration, decrypts the API credentials in memory via AES-256-CBC, constructs the secure HTTP request, forwards it to the target service, and returns the response in standard MCP format.

---

Tech Stack

• Framework: Next.js 15 (App Router), React 19, TypeScript
• Styling & UI: Tailwind CSS + shadcn/ui (new-york style), lucide-react, sonner
• Database: Prisma ORM with PostgreSQL
• Protocol & Communication: @modelcontextprotocol/sdk, axios, zod

Project Structure

app/
  (dashboard)/integrations/...   # Responsive management dashboard (Server Components)
  api/integrations/**            # REST API Route Handlers for dashboard config
  api/mcp/route.ts               # MCP HTTP transport route (listTools, callTool)
lib/
  db.ts                          # Prisma database client singleton
  server/crypto.ts               # AES-256-CBC encryption for credential security
  server/ssrf-guard.ts           # SSRF protection layer for secure URL imports
  server/spec-parser.ts          # OpenAPI/Swagger spec parsing logic
  server/services/*              # Business logic services (integrations, credentials, specs)
  mcp/*                          # MCP core server, proxying and schema translation
  validation/schemas.ts          # Zod validation schemas
components/ui/*                  # Shared shadcn/ui components
components/features/*            # Integration, credential, spec, endpoint, and tool dashboard panels
mcp/stdio.ts                     # Claude Desktop stdio MCP server entrypoint
prisma/schema.prisma             # PostgreSQL database schema

Installation & Setup

Prerequisites

• Node.js 18+ (Node.js 22 recommended)
• PostgreSQL database instance

Step 1: Clone and Install

git clone https://github.com/volkan-m/APItoMCPGateway.git
cd APItoMCPGateway
npm install

Step 2: Configure Environment

Copy the example environment file and adjust the values:

cp ENV.EXAMPLE .env

Step 3: Database Migration

Generate Prisma client and run migrations:

npx prisma generate
npx prisma migrate deploy

Step 4: Run Development Server

npm run dev

Open http://localhost:3000 in your browser.

---

Environment Variables

Variable	Description
DATABASE_URL	PostgreSQL connection string (Prisma)
ENCRYPTION_KEY	Key used to encrypt and decrypt API credentials at rest (32-character string).
BEARER_TOKEN	Optional fallback authorization token for the proxy.
AUTH_TOKEN	Secret token used to secure the dashboard and API endpoints. If left blank, auth is disabled (development mode).
ADMIN_PASSWORD	Password required to log into the web dashboard (used alongside AUTH_TOKEN).
INTEGRATION_ID	Default integration ID used when starting the stdio server (mcp/stdio.ts).
MCP_PROXY_INSECURE_TLS	Set to true to disable TLS certificate verification (useful for internal/self-signed target APIs).
MCP_TOOL_CACHE_TTL_MS	Cache TTL (ms) for endpoint definitions in the MCP HTTP transport. Default: 5000.

---

MCP Client Integration

Option A: HTTP (Cursor, n8n, etc.)

Send a POST request to /api/mcp with the header X-Integration-Id:

• List Tools:

curl -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $AUTH_TOKEN" \
  -H "X-Integration-Id: <integration-id>" \
  -d '{ "method": "listTools" }'

• Call Tool:

curl -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $AUTH_TOKEN" \
  -H "X-Integration-Id: <integration-id>" \
  -d '{
        "method": "callTool",
        "params": { "name": "<tool-name>", "arguments": {} }
      }'

Option B: stdio (Claude Desktop)

Add the configuration below to your claude_desktop_config.json:

{
  "mcpServers": {
    "api-to-mcp": {
      "command": "npm",
      "args": ["run", "mcp:stdio"],
      "cwd": "c:/Sources/BruteForceRepo/APItoMCPGateway",
      "env": { "INTEGRATION_ID": "<integration-id>" }
    }
  }
}

---

Contributing & Open Source

Contributions are highly welcome! We follow standard open-source conventions:

1. Fork the repository on GitHub.
2. Create a feature branch from main (git checkout -b feature/amazing-feature).
3. Commit your changes with clear and descriptive messages.
4. Make sure your code compiles and matches the project structure (npm run typecheck).
5. Open a Pull Request explaining your enhancements or bug fixes.

---

License

This project is licensed under the MIT License. Feel free to use, modify, and distribute it.

---

<a name="türkçe"></a>

Türkçe

API to MCP Gateway, standart REST/OpenAPI Web API'leri ile Model Context Protocol (MCP) arasında köprü vazifesi gören, modern ve açık kaynaklı bir platformdur. REST uç noktalarını dinamik olarak MCP araçlarına (tool) dönüştürerek LLM istemcilerinin (Cursor, Claude Desktop, n8n gibi) API'lerinizle birleşik bir arayüz üzerinden güvenli ve yerel şekilde çalışmasını sağlar.

Tamamen modern ve yüksek performanslı bir teknoloji yığını (TypeScript + Next.js App Router) ile geliştirilen proje; API yönetimi, OpenAPI şeması aktarımı, güvenli kimlik bilgisi şifreleme ve MCP sunucusu barındırma işlemlerini tek bir çatı altında toplar.

Temel Özellikler

• 🔌 Dinamik OpenAPI Analizi: OpenAPI/Swagger spesifikasyon dosyalarını yükleyerek veya uzak bir URL'den çekerek uç noktalarınızı anında kaydedin.
• 🛠️ Otomatik Araç Çıkarımı: REST uç noktalarını standart MCP araçlarına (tools) otomatik olarak dönüştürün.
• 🔒 Güvenli Kimlik Bilgisi Depolama: API anahtarlarını, token'ları ve başlık bilgilerini veritabanında askeri düzeyde AES-256-CBC algoritmasıyla şifrelenmiş olarak saklayın.
• 🛡️ SSRF Koruması: Uzak şemaları içe aktarırken Server-Side Request Forgery (Sunucu Tarafı İstek Sahteciliği) açıklarını engelleyen dahili güvenlik mekanizması.
• 🚀 Çift Yönlü MCP Sunumu: Hem web/bulut entegrasyonları (n8n gibi) için uygun bir HTTP MCP uç noktası hem de yerel istemciler (Claude Desktop gibi) için ideal bir stdio MCP süreci sunar.
• 💻 Modern Yönetim Paneli: Entegrasyonları, kimlik bilgilerini, uç noktaları ve araçları tamamen duyarlı (responsive) bir web arayüzü üzerinden yönetin.

---

Sistem Mimarisi

graph TD
    %% Subgraph 1: İstemciler
    subgraph Clients ["<font size=4 color='#3b82f6'>■ İstemciler / LLM Sunucuları</font>"]
        Claude["<b>Claude Desktop</b><br/><i>(stdio)</i>"]
        Cursor["<b>Cursor / IDE</b><br/><i>(HTTP)</i>"]
        n8n["<b>n8n İş Akışları</b><br/><i>(HTTP)</i>"]
        Admin["<b>Geliştirici / Yönetici</b><br/><i>(Tarayıcı)</i>"]
    end

    %% Subgraph 2: Gateway
    subgraph Gateway ["<font size=4 color='#10b981'>■ Next.js Gateway Uygulaması</font>"]
        STDIO["<b>stdio Girişi</b><br/><i>mcp/stdio.ts</i>"]
        HTTP_EP["<b>HTTP MCP Uç Noktası</b><br/><i>api/mcp/route.ts</i>"]
        UI["<b>Yönetim Paneli (UI)</b><br/><i>app/(dashboard)</i>"]
        
        ServerCore["<b>MCP Sunucu Çekirdeği</b><br/><i>lib/mcp/server.ts</i>"]
        Parser["<b>Spesifikasyon Ayrıştırıcı</b><br/><i>lib/server/spec-parser.ts</i>"]
        Proxy["<b>API Proxy Katmanı</b><br/><i>lib/mcp/api-proxy.ts</i>"]
        Crypto["<b>Crypto Servisi</b><br/><i>lib/server/crypto.ts</i>"]
    end

    %% Subgraph 3: Veri Tabanı
    subgraph Storage ["<font size=4 color='#a78bfa'>■ Veritabanı / Veri Katmanı</font>"]
        Prisma["<b>Prisma ORM</b><br/><i>lib/db.ts</i>"]
        DB[("<b>PostgreSQL Veritabanı</b>")]
    end

    %% Subgraph 4: Dış Servisler
    subgraph External ["<font size=4 color='#f59e0b'>■ Hedef Servisler / Dış API'ler</font>"]
        ExtAPI["<b>Dış Web API'leri</b><br/><i>(Hedef Uç Noktalar)</i>"]
    end

    %% Bağlantılar
    %% İstemcilerden Giriş Noktalarına
    Claude ==> STDIO
    Cursor ==> HTTP_EP
    n8n ==> HTTP_EP
    Admin ==> UI

    %% Giriş Noktalarından Çekirdek İşlemlere
    STDIO --> ServerCore
    HTTP_EP --> ServerCore
    
    %% Arayüz ve Ayrıştırıcı Akışı
    UI --> Parser
    Parser --> Prisma
    
    %% Çekirdek Veri Erişimleri
    ServerCore --> Prisma
    Prisma --> DB
    
    %% İstek Yönlendirme & Şifre Çözme Akışı
    ServerCore --> Proxy
    Proxy <--> Crypto
    Proxy ==> ExtAPI

    %% Düğüm Stilleri
    classDef clientNode fill:#1e2937,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef gatewayNode fill:#1f2937,stroke:#10b981,stroke-width:2px,color:#fff;
    classDef dbNode fill:#1e1b4b,stroke:#a78bfa,stroke-width:2px,color:#fff;
    classDef extNode fill:#78350f,stroke:#f59e0b,stroke-width:2px,color:#fff;

    class Claude,Cursor,n8n,Admin clientNode;
    class STDIO,HTTP_EP,UI,ServerCore,Parser,Proxy,Crypto gatewayNode;
    class Prisma,DB dbNode;
    class ExtAPI extNode;

    %% Alt Grafik Stilleri
    style Clients fill:#111827,stroke:#3b82f6,stroke-width:2px;
    style Gateway fill:#0b0f19,stroke:#10b981,stroke-width:2px;
    style Storage fill:#11101b,stroke:#a78bfa,stroke-width:2px;
    style External fill:#14110b,stroke:#f59e0b,stroke-width:2px;

Sistemin Çalışma Mantığı

1. Yönetim ve Yapılandırma: Geliştiriciler, yönetim paneli aracılığıyla entegrasyonları tanımlar, OpenAPI şemalarını sisteme aktarır ve ilgili API kimlik bilgilerini güvenli bir şekilde kaydeder.
2. Veritabanı Kaydı: Şemalar otomatik olarak çözümlenerek Prisma ORM yardımıyla PostgreSQL veritabanına yapılandırılmış uç noktalar olarak kaydedilir.
3. MCP Sunumu: Gateway, hem HTTP hem de stdio kanalları üzerinden gelen talepleri dinler.
4. Proxy ve Güvenlik: LLM bir aracı çalıştırdığında, Gateway uç nokta tanımını yükler, API anahtarlarını bellek üzerinde AES-256-CBC ile çözer, güvenli HTTP isteğini oluşturup hedef dış servise iletir ve yanıtı MCP standart formatında istemciye geri döner.

---

Teknoloji Yığını

• Framework: Next.js 15 (App Router), React 19, TypeScript
• Tasarım & UI: Tailwind CSS + shadcn/ui (new-york tarzı), lucide-react, sonner
• Veritabanı: Prisma ORM ve PostgreSQL
• Protokol: @modelcontextprotocol/sdk, axios, zod

Proje Yapısı

app/
  (dashboard)/integrations/...   # Duyarlı yönetim paneli (Server Components)
  api/integrations/**            # Yönetim paneli yapılandırma REST API Route Handler'ları
  api/mcp/route.ts               # MCP HTTP taşıyıcı uç noktası (listTools, callTool)
lib/
  db.ts                          # Prisma veritabanı istemcisi singleton
  server/crypto.ts               # Kimlik bilgileri güvenliği için AES-256-CBC şifreleme
  server/ssrf-guard.ts           # Güvenli URL içe aktarımları için SSRF koruması
  server/spec-parser.ts          # OpenAPI/Swagger spesifikasyonu ayrıştırma mantığı
  server/services/*              # İş mantığı servisleri (entegrasyonlar, kimlik bilgileri, specs)
  mcp/*                          # MCP çekirdek sunucusu, yönlendirme ve şema dönüşümü
  validation/schemas.ts          # Zod doğrulama şemaları
components/ui/*                  # Paylaşılan shadcn/ui bileşenleri
components/features/*            # Arayüz entegrasyon, kimlik bilgisi, endpoint ve tool panelleri
mcp/stdio.ts                     # Claude Desktop stdio MCP sunucu giriş noktası
prisma/schema.prisma             # PostgreSQL veritabanı şeması

Kurulum ve Yapılandırma

Gereksinimler

• Node.js 18+ (Node.js 22 önerilir)
• PostgreSQL veritabanı sunucusu

Adım 1: Projeyi Klonlayın ve Bağımlılıkları Kurun

git clone https://github.com/volkan-m/APItoMCPGateway.git
cd APItoMCPGateway
npm install

Adım 2: Ortam Değişkenlerini Ayarlayın

Örnek ortam dosyasını kopyalayın ve değerleri düzenleyin:

cp ENV.EXAMPLE .env

Adım 3: Veritabanı Şemasını Uygulayın

Prisma istemcisini oluşturun ve veritabanı tablolarını hazırlayın:

npx prisma generate
npx prisma migrate deploy

Adım 4: Geliştirme Sunucusunu Başlatın

npm run dev

Tarayıcınızda http://localhost:3000 adresini açarak yönetim paneline ulaşabilirsiniz.

---

Ortam Değişkenleri

Değişken	Açıklama
DATABASE_URL	PostgreSQL bağlantı adresi (Prisma)
ENCRYPTION_KEY	API kimlik bilgilerini veritabanında şifrelemek ve çözmek için kullanılan 32 karakterlik anahtar.
BEARER_TOKEN	Proxy istekleri için isteğe bağlı fallback yetkilendirme belirteci (token).
AUTH_TOKEN	Yönetim paneli ve API uç noktalarını korumak için kullanılan gizli anahtar. Boş bırakılırsa koruma devre dışı kalır (geliştirme modu).
ADMIN_PASSWORD	Yönetim paneline giriş için gerekli şifre (AUTH_TOKEN ile birlikte kullanılır).
INTEGRATION_ID	stdio sunucusu (mcp/stdio.ts) başlatıldığında kullanılacak varsayılan entegrasyon ID'si.
MCP_PROXY_INSECURE_TLS	TLS sertifika doğrulamasını kapatmak için true yapın (dahili/self-signed hedef API'ler için).
MCP_TOOL_CACHE_TTL_MS	MCP HTTP taşıyıcısında endpoint tanımları için önbellek süresi (ms). Varsayılan: 5000.

---

MCP İstemci Entegrasyonu

Yöntem A: HTTP (Cursor, n8n vb.)

/api/mcp adresine X-Integration-Id başlığı ile bir POST isteği gönderin:

• Araçları Listele (List Tools):

curl -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $AUTH_TOKEN" \
  -H "X-Integration-Id: <integration-id>" \
  -d '{ "method": "listTools" }'

• Araç Çağır (Call Tool):

curl -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $AUTH_TOKEN" \
  -H "X-Integration-Id: <integration-id>" \
  -d '{
        "method": "callTool",
        "params": { "name": "<tool-name>", "arguments": {} }
      }'

Yöntem B: stdio (Claude Desktop)

Aşağıdaki yapılandırmayı claude_desktop_config.json dosyanıza ekleyin:

{
  "mcpServers": {
    "api-to-mcp": {
      "command": "npm",
      "args": ["run", "mcp:stdio"],
      "cwd": "c:/Sources/BruteForceRepo/APItoMCPGateway",
      "env": { "INTEGRATION_ID": "<integration-id>" }
    }
  }
}

---

Katkıda Bulunma & Açıklık Politikası

Katkılarınızı sabırsızlıkla bekliyoruz! Standart açık kaynaklı iş akışlarını takip ediyoruz:

1. Bu depoyu fork edin.
2. main dalından yeni bir özellik dalı oluşturun (git checkout -b feature/amazing-feature).
3. Değişikliklerinizi açıklayıcı commit mesajlarıyla commit edin.
4. Kodun derlendiğinden ve hata içermediğinden emin olun (npm run typecheck).
5. Geliştirmelerinizi açıklayan bir Pull Request (PR) açın.

---

Lisans

Bu proje MIT Lisansı ile lisanslanmıştır. Özgürce kullanabilir, değiştirebilir ve dağıtabilirsiniz.