MCP sunucusu

Nedir?

MCP, AI araçlarının harici hizmetlere bağlanması için açık bir standarttır. formbase, Claude Code, Claude desktop ve Cursor dahil olmak üzere her MCP uyumlu istemcinin bağlanabileceği barındırılan bir MCP uç noktası sunar.

Bağlantı

URL:  https://api.formbase.so/api/mcp   (POST, streamable HTTP)
Auth: Bearer <token>

İki tür bearer token çalışır:

• API token (fb_…) — API token’ları sayfasından oluşturulur. Kişisel kullanım ve hızlı kurulum için en uygunudur.

• OAuth erişim token’ı (fbo_…) — OAuth akışı tarafından verilir. Bir kullanıcı adına bağlanan üçüncü taraf uygulamalar için en uygunudur.

Her ikisi de tam olarak bir çalışma alanına bağlıdır ve aynı araçlara ulaşır. Başka bir çalışma alanını veya o çalışma alanındaki bir formu belirten bir araç çağrısı FORBIDDEN ile başarısız olur. OAuth token’ları ayrıca kapsam taşır (mcp:read, mcp:write, offline_access), ancak bugün hiçbir araç bunlara göre kısıtlanmaz — herhangi bir token’ı, çalışma alanı içinde tam erişim olarak değerlendirin.

Araç çağrıları token başına dakikada 120 ile sınırlıdır ve bu sınır API ile paylaşılır: yalnızca tools/call bu bütçeyi harcar, initialize, tools/list, prompts/ ve resources/ ücretsizdir. Bütçe aşıldığında çağrı yine de HTTP 200 döner, ancak başarısız bir araç sonucu RATE_LIMITED ve bir retryAfterMs taşır — döngü içinde değil, bir zamanlayıcıyla yoklayın.

Temel araçlar

Bir istemci bağlandığında tools/list üzerinde her araç tanıtılır. Claude Code gibi şemaları isteğe bağlı yükleyen istemciler, bir görev ihtiyaç duyduğunda bir aracın tam şemasını getirir. Aşağıdaki tablo çoğu görevin başladığı temel araçları kapsar; load_tools (kataloglar) ile load_skill (alan kılavuzları) geri kalanını belgeler.

Daha fazla ekleme çeşidi — saat, dosya yükleme, imza, ödeme, matris/ızgara, sıralama, resim seçimi, açma/kapama düğmesi, tablo, liste, satır, hesaplanmış alan, gizli alan, satır içi değişken, gömülü içerik (YouTube, Google Maps veya iframe gömmek için editor_insertEmbedded) ve koşullu mantık bloğu (editor_insertLogic) — bunlar da tools/list üzerindedir. Araç adı ve alanlarıyla birlikte tam set için load_skill(“question-types”) yükleyin. Koşullu mantık, editor-actions kataloğundaki editor_setLogic ile oluşturulur.

Araç katalogları

Bu araçlar da tools/list üzerindedir. Gruplandırılmış araçlar için zenginleştirilmiş belgeler (giriş, tam şemalar, kullanım kalıpları, uç durumlar) almak üzere bir katalog adıyla load_tools çalıştırın, ardından doğrudan çağırın.

request-lifecycle kataloğu sekiz istek aracının tamamını listeler çünkü uygulama içi sohbet daha küçük bir temel set tanıtır. Bu uç noktada sekizi de zaten tools/list üzerindedir, bu yüzden kataloğun eklediği şey belgelerdir.

Beceriler (etki alanı bilgisi)

Beceriler, ajanın load_skill aracılığıyla yükleyebileceği yerleşik kılavuzlardır. Ajanın daha iyi kararlar almasına yardımcı olan etki alanı bilgisi sağlarlar — araç şemaları değil, tasarım tavsiyeleri ve alan anlamları.

İstekler

Bir istek, yayınlanmış bir formu tek bir adlandırılmış alıcıya atar; kendi bağlantısı, kendi önceden doldurulmuş yanıtları ve kendi sonucuyla. Bir ajanın gerçek bir kişiden bir şey istemesinin ve ne söylediğini öğrenmesinin yoludur.

Bir istek oluşturmak

Her zaman fields_list(formId) ile başlayın. Formun geçerli yayınlanmış sürümünün adreslenebilir anahtarlarını, anahtarın hangi argümana ait olduğunu belirten bir usage satırıyla birlikte döndürür — görünür sorular prefill içine, gizli alanlar context içine gider. Bir anahtarı asla bir soru başlığından türetmeyin ve form_publish’ten sonra yeniden okuyun.

{
  "formId": "j57...",
  "recipient": { "email": "ada@acme.com", "name": "Ada" },
  "prefill": { "company_name": "Acme", "plan": "pro" },
  "readonly": ["company_name"],
  "context": { "crm_id": "A-42" },
  "metadata": { "run_id": "exec_918" },
  "delivery": "email",
  "expiresAt": 1780000000000,
  "callbackUrl": "https://hooks.acme.com/formbase",
  "idempotencyKey": "po-42"
}

Sonuç, bağlantıyı ve saati taşır:

{
  "id": "kd7...",
  "status": "pending",
  "url": "https://form.formbase.so/r/rq_...",
  "deliveryStatus": "queued",
  "expiresAt": 1780000000000,
  "createdAt": 1747000000000,
  "deduplicated": false,
  "next": "..."
}

delivery varsayılan olarak “none”’dur, bu da url’yi kendinizin teslim etmesi gerektiği anlamına gelir; “email” daveti gönderir ve Pro veya Business planda ya da Ücretsiz bir hesabın 10 ücretsiz davetinden birinde recipient.email gerektirir. readonly, alıcının düzenleyemeyeceği alanları kilitler ve kilitli her anahtar aynı zamanda önceden doldurulmuş olmalıdır. context yalnızca gizli alan anahtarlarını kabul eder, metadata ise request_get’te ve geri çağırmada olduğu gibi geri döndürülen opak bir kayıt bilgisidir. expiresAt epoch milisaniye cinsindendir, varsayılan 30 gün ve azami 365 gündür. idempotencyKey 30 gün boyunca çalışma alanı kapsamlıdır: aynı gövdeyle aynı anahtar, deduplicated: true ile birlikte orijinal isteği döndürür, farklı bir gövde ise çakışma sayılır. Her yanıt ayrıca ajana buradan sonra ne yapması gerektiğini söyleyen bir next satırı taşır.

deliveryStatus, bir davet sıraya alınana kadar not_requested’dır, ardından queued → sent veya failed olur ve posta sağlayıcısı sert bir geri dönüşü (bounce) ya da şikayeti bildirdiğinde bounced olur. Bir istek oluşturmak, alıcı hiç yanıt vermese bile çalışma alanının aylık ödeneğinden bir birim harcar; bu ödenek tükendiğinde request_create, MONTHLY_ALLOWANCE_REACHED ile başarısız olur.

Geri çağırmalar veya yoklama

Bir callbackUrl ile, formbase her nihai olayda bir kez POST gönderir — tamamlanma, süre dolumu, iptal — çalışma alanının istek imzalama sırrıyla imzalanmış olarak. Yük (payload) ve doğrulama tarifi için Geri çağırmalar ve imzalama sayfasına bakın.

Test modu

Gerçek bir çalıştırmadan önce tüm yapıyı denemek için test: true geçirin. Bağlantı yine açılır ve tamamlanabilir, geri çağırma “test”: true ile tetiklenir — ama delivery ne derse desin hiçbir şey e-postayla gönderilmez, istek İstekler sayfasından ve analiz hunisinden gizli kalır ve gönderimi hiçbir yerde sayılmaz: kota yok, dışa aktarım yok, entegrasyon yok. Test istekleri yalnızca includeTest: true geçirdiğinizde request_list’te görünür. Bağlantı 24 saat içinde kapanır ve Free’de bir workspace günde 10 test isteği oluşturabilir.

İstek başına belgeler

Bir alıcıya dosya vermek için — bir sözleşme taslağı, kendi teklifi — formun bir Belgeler bloğuna ihtiyacı vardır; bunu bir yazar veya bir ajan editor_insertDocumentsBlock ile ekler. fields_list bunu type: “documents” olarak bildirir. Baytlar hiçbir zaman bir araçtan geçmez:

1. formId, name, contentType ve bayt cinsinden tam size ile document_create çağırın. { id, name, contentType, size, uploadUrl, expiresAt } geri alırsınız. Yalnızca PDF ve görseller (Office belgeleri olmaz), dosya başına 25 MB ve istek başına 100 MB belge.

2. Ham baytları, bir saat içinde, beyan ettiğiniz türe ayarlanmış Content-Type ile uploadUrl’e PUT edin.

3. Bunu request_create’ten referans verin: documents: [{ documentId, field?, name? }]. field, Belgeler bloğunun alan anahtarıdır; yalnızca formda tam olarak bir böyle blok varsa isteğe bağlıdır. name bu istek için görünen adı geçersiz kılar.

Bloğun hazırlanmış belgeleri yerinde kalır ve sizinkiler bunların altında görünür, yalnızca bu alıcı için. request_create, istek var olmadan önce yüklemeyi doğrular, bu yüzden DOCUMENT_NOT_UPLOADED, 2. adımın atlandığı anlamına gelir. Bir yükleme, istediğiniz kadar istek tarafından referans verilebilir ve baytları çalışma alanı depolamanıza sayılır.

Özel alan adları

Bağlantıyı çalışma alanının özel alan adlarından birinde oluşturmak için request_create’e domainId geçirin. Kimlikler, bunları availableCustomDomains olarak döndüren formShareLink_list’ten gelir. Atlarsanız, bağlantı formun zaten yayınlandığı alan adını alır.

Sonuçları okumak

request_get isteğin tamamını döndürür. Tamamlandıktan sonra answers, alıcının değerlerini alan anahtarına göre anahtarlanmış olarak tutar, display aynı anahtarları okunabilir metin olarak taşır ve outcome — approve, decline veya changes — form bir karar sorusu içeriyorsa alıcının kararıdır. Bir callbackFailedAt zaman damgası, teslimatın yeniden deneme hakkının tükendiği ve uç noktanıza hiçbir şeyin ulaşmadığı anlamına gelir; alıcıyı düzeltin, ardından orijinal olay kimliğini yeniden gönderen request_replayCallback’i çağırın, böylece alıcınız yeniden çalıştırmak yerine tekilleştirme (dedupe) yapar. Formun saklama politikası bir isteği temizledikten sonra dataPurgedAt ayarlanır ve yanıtlar sonsuza dek kaybolur.

request_list, status, outcome, externalId ve includeTest’e göre filtrelenmiş şekilde birçoğunu tek seferde tarar. nextCursor ile sayfalandırın: bir sayfa nadiren boş bir items ve hasMore: true ile dönebilir, bu listenin sonu değildir — imleci geri gönderin ve devam edin.

Kaynaklar ve promptlar

Her beceri ve araç kataloğu aynı zamanda skill://<name> adresinde bir MCP kaynağıdır — skill://requests, skill://editor-inserts. resources/list’i destekleyen bir istemci, load_skill veya load_tools çağırmadan bunlara göz atabilir ve okuyabilir. Sunucu ayrıca prompts/list üzerinde dört prompt sunar: identity, capabilities, data_tools ve editor_tools.

Önce onay isteyen araçlar

Her araç, fiiline göre türetilen readOnlyHint ve destructiveHint MCP ipuçlarını taşır. Şu araçlar yıkıcı (destructive) olarak işaretlenmiştir, çünkü geri almak başka bir çağrı gerektirir ya da mümkün değildir: form_delete, form_unpublish, workspaceFolder_delete, editor_deleteElement, translationLanguage_delete ve request_cancel. Çoğu istemci bunları çalıştırmadan önce kullanıcıya sorar, ancak bu istem istemcinin kararıdır; kesin bir durdurma istiyorsanız istemcinin onay ayarlarını kontrol edin.

Sınırlamalar

• Bir araç çağrısı üzerinden ikili (binary) yükleme yok. Resimler URL ile ayarlanır: kapaklar, logolar ve resim blokları http(s):// veya data:image URI’lerini kabul eder. İstek başına bir belge bunun istisnasıdır: document_create, HTTP erişimi olan bir istemcinin dosyayı PUT edebileceği bir yükleme URL’si döndürür (bkz. İstek başına belgeler). Bir PDF’yi veya ekran görüntüsünü forma dönüştürmek için yerleşik AI sohbetini kullanın.

• Çalışma alanı AI Becerileri yok. formbase’de yazılan beceriler yalnızca yerleşik AI sohbetinde kullanılabilir. Sunucunun kendi becerileri (load_skill) MCP üzerinden kullanılabilir.

API token’ı ile bağlanma

Çoğu istemci OAuth ile oturum açar: başlık eklemeden URL’yi ekleyin ve AI ajanı bağlama kılavuzunu izleyin. Bir tarayıcı açamayan istemciler — bir betik, CI görevi veya başsız (headless) bir ajan gibi — bunun yerine bir API token’ını başlık olarak gönderir.

Komut satırından Claude Code:

claude mcp add --transport http formbase https://api.formbase.so/api/mcp \
  --header "Authorization: Bearer fb_YOUR_TOKEN"

Ya da bir projenin .mcp.json dosyasında:

{
  "mcpServers": {
    "formbase": {
      "type": "http",
      "url": "https://api.formbase.so/api/mcp",
      "headers": {
        "Authorization": "Bearer fb_YOUR_TOKEN"
      }
    }
  }
}

Cursor, .cursor/mcp.json veya ~/.cursor/mcp.json içinde:

{
  "mcpServers": {
    "formbase": {
      "url": "https://api.formbase.so/api/mcp",
      "headers": {
        "Authorization": "Bearer fb_YOUR_TOKEN"
      }
    }
  }
}

Bir token yerine OAuth ile oturum açmak için Cursor’a ekle bağlantısını kullanın. Sunucu URL’sini başlıksız ekler ve Cursor sizden formbase’de oturum açmanızı ister.

Diğer istemciler aynı URL ve başlığı kullanır; nereye ekleyeceğinizi kendi belgelerinden kontrol edin.

API token’ları yerine OAuth kullanmak

Bir kullanıcı adına bağlanan üçüncü taraf bir uygulama, yapıştırılmış bir token istemek yerine OAuth kullanmalıdır. formbase, zorunlu PKCE (S256) ve opak token’lara sahip bir OAuth 2.1 yetkilendirme sunucusudur — JWT yok, örtük (implicit) izin akışı yok. Claude desktop, Claude Code ve Claude.ai web bağlayıcısı bunların tümünü MCP uç noktasından keşfeder, bu yüzden başlıksız yalnızca URL’yi yapıştırmak yeterlidir: 401 yanıtı /.well-known/oauth-protected-resource adresine işaret eder ve istemci oradan devam eder.

Kendi yazdığınız bir istemci için akış:

1. Uç nokta URL’leri, kapsamlar ve desteklenen kimlik doğrulama yöntemleri için önce GET /.well-known/oauth-protected-resource ve ardından GET /.well-known/oauth-authorization-server.

2. redirect_uris’inizle POST /oauth/register (dinamik istemci kaydı, kimlik bilgisi gerekmez). Bir client_id ve, token_endpoint_auth_method: “none” dışında bir şey istediyseniz bir client_secret alırsınız. Yönlendirme URI’leri HTTPS olmalı, ya da localhost üzerinde HTTP olabilir. Kayıt, IP başına saatte 20 ile sınırlıdır.

3. Kullanıcıyı response_type=code, client_id’niz, kayıtlı redirect_uri, scope=mcp:read mcp:write offline_access, state ve code_challenge_method=S256 ile bir code_challenge parametreleriyle /oauth/authorize’a gönderin. Kullanıcı oturum açar, bir çalışma alanı seçer ve yetkilendirir.

4. Kodu, 60 saniye içinde grant_type=authorization_code ve code_verifier’ınızla POST /oauth/token’da değiştirin. Kodlar tek kullanımlıktır.

5. MCP uç noktasını Authorization: Bearer fbo_… ile çağırın. Erişim token’ları 1 saat sürer; yenileme token’ları 30 gün sürer ve her kullanımda döner. Harcanmış bir yenileme token’ını yeniden kullanmak tüm zinciri geçersiz kılar, bu yüzden en yenisini saklayın.

POST /oauth/revoke (RFC 7009) bir erişim veya yenileme token’ını iptal eder. Bir kullanıcı, OAuth ve API Anahtarları sayfasındaki Bağlı uygulamalar bölümünden uygulamanın tamamının bağlantısını da kesebilir; bu, uygulamanın o çalışma alanı için tuttuğu her token’ı öldürür.

Elinizde zaten bir token varsa, onu bir API anahtarıyla aynı yere koyarsınız:

{
  "mcpServers": {
    "formbase": {
      "type": "http",
      "url": "https://api.formbase.so/api/mcp",
      "headers": {
        "Authorization": "Bearer fbo_USER_OAUTH_TOKEN"
      }
    }
  }
}

Bağlı uygulamalar

Her OAuth bağlantısı, OAuth ve API Anahtarları sayfasındaki Bağlı uygulamalar altında, ne zaman bağlandığı ve son ne zaman kullanıldığı bilgisiyle birlikte listelenir. Bağlantılar kişiseldir: yalnızca onu yetkilendiren kullanıcı görür, çalışma alanı yöneticileri başka bir üyenin bağlantısını görüntüleyemez veya iptal edemez. Bağlantıyı kesmek anında etkili olur. Çalışma alanından ayrılan veya çıkarılan bir kullanıcı, o çalışma alanına ait tüm bağlantılarını kaybeder.

Sonraki adımlar