MCP sunucusu

Nordlet, Model Context Protocol desteğini https://api.nordlet.com/mcp adresinde sunar. Bu adrese bağlanan bir yapay zeka asistanı; doğrudan bir istekte olduğu gibi aynı API anahtarı, şirket ve yetki kapsamlarıyla (scopes) API'de arama yapabilir, herhangi bir işlemin istek şemasını okuyabilir ve bu işlemi çağırabilir. Her araç çağrısı (tool call) sıradan bir API isteğidir: tıpkı onlar gibi kimlik doğrulanır, oran sınırı (rate limit) uygulanır ve kullanım ölçümü yapılır. Veri değiştiren (mutating) bir çağrı ise şirketin defterlerini günceller.

Bağlantı

Uç nokta (endpoint), Streamable HTTP protokolünü kullanır ve Başlangıç kılavuzu bölümünden alınan Bearer API anahtarıyla kimlik doğrulaması yapar. Claude Code içinde:

claude mcp add --transport http nordlet https://api.nordlet.com/mcp --header "Authorization: Bearer nl_..."

Diğer tüm MCP istemcileri de aynı URL'yi ve başlığı kullanır. *:read yetkisiyle sınırlandırılmış bir anahtar yalnızca okuma işlemlerini çağırabilir; araçlar, eksik yetki kapsamlarını API'nin 403 hatası olarak bildirir.

Araçlar

API'nin tüm işlemlerini üç araç kapsar:

Araç	Ne yapar
search_operations	İşlemleri adındaki, yolundaki (path), özetindeki veya açıklamasındaki kelimelere göre, isteğe bağlı olarak tek bir modül (sales, bank, reports, ...) içinde arar. Sorgu verilmezse modülleri listeler.
describe_operation	Bir işlemin metodunu, yolunu, açıklamasını ve JSON istek şemasını döndürür; includeResponse: true parametresi ise 200 yanıtının şemasını ekler.
includeResponse: true	Bir işlemi JSON gövdesiyle çalıştırır. Yanıt gövdesi JSON olarak döner; 4xx veya 5xx yanıtları, durum kodu ve hata zarfıyla birlikte bir araç hatası olarak döner. İsteğe bağlı bir idempotencyKey, Idempotency-Key başlığı olarak gönderilir, böylece aynı anahtarla tekrarlanan bir çağrı, etkiyi yinelerlemek yerine ilk yanıtı yeniden oynatır.

En sık kullanılan işlemler aynı zamanda kendi istek şemalarına sahip doğrudan araçlardır, böylece bir asistan arama yapmaya gerek kalmadan bu alanları görebilir: partners_list, partners_get, partners_create, partners_find_or_create, catalog_items_list, sales_invoices_list, sales_invoices_get, sales_invoices_create, sales_invoices_issue, sales_invoices_send, purchases_invoices_list, purchases_invoices_create, purchases_invoices_register, bank_transactions_list, bank_transactions_import, bank_transactions_match, ledger_journal_transactions_list, reports_trial_balance, reports_financial_statements, reports_vat_summary ve reports_debt_aging. Her araç, istemciye yazma işlemi yapıp yapmadığını bildiren MCP ek açıklamalarını (readOnlyHint, destructiveHint) barındırır.

İşlem dizini ve şemalar, API referansı ve SDK'larla aynı OpenAPI tanımından oluşturulur, bu nedenle API'ye eklenen bir işlem, o sürümle birlikte search_operations içinde görünür hale gelir. Sunucu talimatları asistana kuralları hatırlatır: tutarlar ondalık dizelerdir (decimal strings), listeler page, pageSize, sort ve filter parametrelerini alır ve ülkeye özgü bir beyanname, o ülkenin dışındaki bir şirket için 422 hatası döndürür.