MCP, AI araçlarının harici hizmetlere bağlanması için açık bir standarttır. Formstep, 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.
İki tür bearer token çalışır:
fb_...) — API token’ları sayfasından oluşturulur.
Kişisel kullanım ve hızlı kurulum için en uygunudur.
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.
> API token’ları oluşturmak ve bağlı OAuth uygulamalarını görüntülemek için çalışma alanı kenar çubuğunuzdaki{' '} > OAuth ve API Anahtarları bölümünü açın. Adım adım kılavuz için API token’ları{' '} > sayfasına bakın. >
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.
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, 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ı.
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.
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.
Sonuç, bağlantıyı ve saati taşır:
``` { "id": "kd7...", "status": "pending", "url": "https://form.formstep.io/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.
Bir callbackUrl ile, Formstep 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.
> İstek imzalama sırrı yalnızca çalışma alanınızdaki Credentials sayfasında görünür — MCP veya API üzerinden asla döndürülmez. Bir alıcı
> kurup yapılandıracak bir insan olmadan kendi başına çalışan bir ajan, bu nedenle bir geri çağırmayı doğrulayamaz.{' '}
> callbackUrl’yi boş bırakın ve bunun yerine status, "pending" olmaktan çıkana kadar saniyeler
> yerine dakikalar mertebesinde request_get(requestId) ile yoklama yapın. expiresAt, bunun ne kadar süre değerli
> olduğunu sınırlar.
>
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.
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:
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.
Content-Type ile uploadUrl’e PUT{' '}
edin.
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.
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.
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.
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.
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.
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.
load_skill) MCP üzerinden kullanılabilir.
Ç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 formstep https://api.formstep.io/api/mcp \ --header "Authorization: Bearer fb_YOUR_TOKEN" ```
Ya da bir projenin .mcp.json dosyasında:
Cursor, .cursor/mcp.json veya ~/.cursor/mcp.json içinde:
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 Formstep’te oturum açmanızı ister.
Diğer istemciler aynı URL ve başlığı kullanır; nereye ekleyeceğinizi kendi belgelerinden kontrol edin.
Bir kullanıcı adına bağlanan üçüncü taraf bir uygulama, yapıştırılmış bir token istemek yerine OAuth kullanmalıdır. Formstep, 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ış:
GET /.well-known/oauth-protected-resource{' '}
ve ardından GET /.well-known/oauth-authorization-server.
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.
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.
grant_type=authorization_code ve code_verifier’ınızla POST /oauth/token’da
değiştirin. Kodlar tek kullanımlıktır.
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": { "formstep": { "type": "http", "url": "https://api.formstep.io/api/mcp", "headers": { "Authorization": "Bearer fbo_USER_OAUTH_TOKEN" } } } } ```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.