Uygulamanızı 30 Dakikada AI Ajanlarına Açın: MCP Entegrasyon Rehberi

Yeni bir uygulama geliştirmek heyecan vericidir — ancak yapay zeka ajanlarının (Claude, Cursor ya da herhangi bir MCP uyumlu araç) bu uygulamayı kullanmak istediğini düşünün. Peki, bu entegrasyonu nasıl gerçekleştireceksiniz?

Çoğu geliştirici, aşağıdaki gibi karmaşık ve bakımı zor çözümlere yöneliyor:

• Özel bir MCP sunucusu yazmak
• JSON-RPC işleyicileri oluşturmak
• Şema tanımlamaları yapmak
• Komut satırı araçları geliştirmek
• OpenAI araç tanımlamaları hazırlamak

Bu süreç, aslında aynı yeteneği üç farklı şekilde yeniden kodlamaktan başka bir şey değil. Her bir entegrasyon, kendi doğrulama mantığı, hata yönetimi ve bakım yükü ile birlikte geliyor. Üstelik, her yeni özellik eklediğinizde bu işlemleri tekrar etmek zorunda kalıyorsunuz.

İşte tam da bu noktada Ageniti devreye giriyor. Ageniti, bir eylemi yalnızca bir kez tanımlamanıza ve otomatik olarak tüm platformlara entegre etmenize olanak tanıyor.

Aynı Eylemi Tüm Platformlarda Kullanabilir Hale Getirin

Ageniti ile bir eylemi tanımladığınızda, sistem otomatik olarak aşağıdaki bileşenleri oluşturuyor:

• MCP araç sunucusu
• Komut satırı arayüzü (CLI) ve JSON çıktısı
• OpenAI uyumlu araç şeması
• Vercel AI SDK araç tanımlamaları

Tüm bunlar, tek bir kaynaktan — eyleminizin tanımından — otomatik olarak üretiliyor. Böylece, her platform için ayrı ayrı kod yazmak zorunda kalmıyorsunuz.

Gerçek Bir Örnek ile Uygulayalım

Diyelim ki bir ürün kataloğunu arama işlevi olan bir fonksiyonunuz var. Bu fonksiyonu tüm platformlarda nasıl kullanabilir hale getireceğinizi adım adım görelim.

Adım 1: Eylemi Tanımlayın

import { action, runtime } from '@ageniti/core';

// Eylemi, girilen ve çıktıları tip güvenliği ile tanımlayın
const searchProducts = action({
  id: 'search-products',
  description: 'Ürün kataloğunu anahtar kelimeye göre ara',
  input: z.object({
    query: z.string().describe('Arama sorgusu'),
    limit: z.number().optional().default(10),
  }),
  handler: async ({ query, limit }) => {
    // Mevcut iş mantığınızı kullanın
    return await productService.search({ query, limit });
  },
});

Adım 2: Tüm Platformlara Yansıtıcıları Oluşturun

// MCP Sunucu (Claude, Cursor vb. için)
import { createMCPServer } from '@ageniti/mcp';
const server = createMCPServer([searchProducts]);
// Çalıştır: node server.js

// Komut Satırı Arayüzü (terminal iş akışları için)
import { createCLI } from '@ageniti/cli';
const cli = createCLI([searchProducts]);
// Çalıştır: ageniti search-products --query "ayakkabı"

// OpenAI Araçları (AI SDK entegrasyonları için)
import { toOpenAITools } from '@ageniti/openai';
const tools = toOpenAITools([searchProducts]);
// Kullan: OpenAI.chat.completions.create({ tools })

Aynı eylem. Üç farklı platform. Hiçbir kod tekrarı olmadan.

Neden Bu Önemli?

Geleneksel yöntemlerle aşağıdaki gibi birçok alanı elle yönetmeniz gerekiyor:

| Endişe Alanı | Elle Yazılan Kod | Ageniti ile Durum | |---------------------|---------------------------|-----------------------| | Giriş Doğrulaması | Her platform için özel | Ortak, tip güvenli | | Hata Yönetimi | Her yerde kopyalanmış | Tek bir yerde | | Şema Senkronizasyonu| Manuel olarak eşleştirme | Otomatik | | CLI Ayrıştırma | Özel bayraklar yazmak | Üretilmiş | | MCP Protokolü | Özel sunucu geliştirme | Hazır entegrasyon |

Her yeni yetenek eklediğinizde, yalnızca tek bir tanım yapmanız yeterli oluyor. Üç ayrı entegrasyonu tekrar tekrar kodlamanız gerekmiyor.

Çalıştırma Katmanı

Ageniti’nin arkasında, her eylemin çalıştığı ortak bir çalıştırma katmanı bulunuyor. Bu katman aşağıdaki gibi görevleri üstleniyor:

• Doğrulama — Zod şemalarıyla sürekli olarak doğrulama yapılır.
• Yetkilendirme — Eylemin çalıştırılmadan önce kancalar (hooks) aracılığıyla kontrol edilir.
• Zaman Aşımı ve Yeniden Deneme — Her eylem için yapılandırılabilir.
• Yapılandırılmış Çıktı — Tutarlı yanıt şekilleri sağlanır.
• Kayıtlar — Eylem çalıştırma kayıtları otomatik olarak tutulur.

const searchProducts = action({
  // ... tanım
  runtime: {
    timeout: 5000,
    retries: 2,
    hooks: {
      before: async (ctx) => {
        if (!ctx.user.canSearch) {
          throw new UnauthorizedError();
        }
      },
    },
  },
});

Fark Yaratan Nedir?

Ageniti, başka bir yapay zeka çatısı ya da orkestrasyon katmanı değil. Uygulamanızın plan yapmasını, mantık yürütmesini ya da yerini almasını sağlamıyor. Aksine, entegrasyon katmanı olarak çalışıyor — ürününüzle bu eylemleri çağırmak isteyen ajanlar arasındaki bağlantıyı sağlıyor.

Bunu şu şekilde düşünebilirsiniz:

• prisma veritabanı şemaları için → Siz eylemleri tanımlıyorsunuz
• react-query API durum yönetimi için → Çalıştırma katmanını kullanıyorsunuz
• zod doğrulama için → Tip güvenliğinizi alıyorsunuz

Uygulama mimariniz aynı kalıyor. Sadece, eylemleri güvenli bir şekilde dış dünyaya açmak için ince bir katman ekliyorsunuz.

Başlarken

Başlamak için komut satırınızda aşağıdakini çalıştırın:

npm install @ageniti/core

Ardından, Başlangıç Rehberi sayfasından adım adım ilerleyebilirsiniz.

Ayrıca, BOOTSTRAP.md dosyasını Cursor ya da Claude Code gibi araçlara vererek, projenizi otomatik olarak klonlayıp kurabilir ve ilk eyleminizi tanımlayabilirsiniz.

Gerçek Kazanç

Amaç, Ageniti’yi kullanmak değil. Uygulamanızın yapay zeka ekosistemiyle sorunsuz çalışmasını sağlamak — haftalarca entegrasyon kodları yazmadan.

Her tanımladığınız eylem, yeni bir platforma (MCP, CLI, OpenAI araçları ya da gelecekteki herhangi bir platform) entegre edildiğinde size zaman ve bakım yükü olarak geri dönecek.

Eğer yapay zeka ajanlarıyla çalışırken entegrasyon karmaşasından kurtulamadıysanız, lütfen nelerin sizi engellediğini paylaşın. Size nasıl yardımcı olabileceğimizi görmek isteriz.