Agentin və tətbiqin işində MCP və API

Agent xarici mənbəyə müraciət etdi, cavabın formatını başa düşdü və xəritəli səhifə hazırladı. İşləyir. İndi bu səhifəni başqa bir insan açır, onda isə Claude Code-dan əsər-əlamət belə yoxdur.

Dərc etməzdən əvvəl bir suala cavab vermək lazımdır. Ziyarətçi üçün verilənləri kim alacaq? İki marşruta, MCP-nin nə iş gördüyünə, qoşulmanı necə yoxlamağa və agentin sessiyasını bağladıqdan sonra nəyin işləməyə davam etməli olduğuna baxaq.

Verilənləri indi kim sorğulayır

İki vəziyyət var və onları qarışdırmaq asandır, çünki ekranda hər ikisi "verilənlər göründü" kimi görünür.

Birinci vəziyyətdə agent mənbəni araşdırır. Siz layihə üzərində işləyirsiniz, Claude Code servisin sənədlərini oxuyur, sorğunu sınayır, cavabın strukturuna baxır. Verilənlər ona kod yazmaq üçün lazımdır. Bu, sizin kompüterinizdə və düz sessiya açıq qaldığı müddətdə baş verir.

İkinci vəziyyətdə ziyarətçi dərc olunmuş səhifəni açır. Verilənlər artıq səhifənin özünə lazımdır - aktual mənzərəni göstərmək üçün. Sorğunu tətbiqin kodu öz işi zamanı göndərir. Məhz buna runtime deyirlər, yəni tətbiqin istifadəçidə işlədiyi vaxt, siz onu yazdığınız vaxt yox.

Üçüncü, aralıq variant da var. Agent bir dəfə mənbəyə müraciət edib cavabı kodun yanında fayla saxlayıb, sayt isə bu faylın məzmununu göstərir. Belə həllin pis heç nəyi yoxdur, hətta nümunə və ya nümayiş üçün rahatdır. Sadəcə bu, anlıq surətdir (snapshot): saxlandığı kimi qalacaq və özünü özü yeniləməyəcək.

İki zəncir ayrı-ayrılıqda yaşayır, aralarında ox yoxdur

Ortadakı qırıq xəttə diqqət yetirin. O, orada gözəllik üçün deyil. Yuxarı və aşağı zəncir arasında ox yoxdur və sxemdən çıxarılmalı əsas nəticə də budur. Mənbə eyni ola bilər, amma ona gedən yol agentin və səhifənin hərəsində ayrıdır. Aşağıda hər zəncirə ayrıca baxacağıq.

MCP nədir

Tapşırıq nadir hallarda yalnız repozitoriyada yaşayır. Bagın təsviri tiketdə qalır, stack trace - monitorinqdə, kitabxananın təzə qaydaları - sənədlərdə, lazımi qeydlər isə verilənlər bazasında.

İnteqrasiya olmadan bütün bunları brauzerdən agentlə söhbətə əllə köçürmək lazım gəlir. Birdəfəlik köçürməyə dözmək olar. Təkrarlanan işdə isə verilənlər köhnəlməyə macal tapır, detalların bir hissəsi itir, eyni yolu isə yenidən keçmək lazım gəlir.

MCP (Model Context Protocol) - Claude Code-un əlçatan xarici alətlər haqqında öyrəndiyi, onları çağırdığı və nəticəni razılaşdırılmış formatda aldığı standartdır. Minimal zəncirdə Claude Code MCP-klient yaradır, klient MCP-serverlə əlaqə saxlayır, server isə öz çıxışı olan sistemə - fayllara, verilənlər bazasına, başqasının API-sinə çatır.

Claude Code MCP-serverlə danışır, server isə xarici sistemlərin yalnız əvvəlcədən təsvir olunmuş imkanlarını açır

Solda daxili MCP-klienti ilə Claude Code, ortada elan olunmuş imkanları olan MCP-server, sağda xarici sistemlər yerləşir. Burada əsas məqam odur ki, agent hər şeyə birdən nəzarətsiz çıxış əldə etmir. O, yalnız serverin təqdim etməyi qərara aldığı əməliyyatları və verilənləri görür.

Hazır MCP-server həm də inteqrasiya işinin bir hissəsindən xilas edir. Hər xarici sistem üçün çağırış formatlarını özünüz təsvir etməli və onun API-sinə müraciət üçün bütün kodu yazmalı olmursunuz. Bununla server məşğul olur, Claude Code isə artıq elan olunmuş əməliyyatlarla işləyir.

Bu zaman server internetdə haradasa ayrıca proqram olmağa borclu deyil. O, birbaşa sizin kompüterinizdə lokal proses kimi işə düşə bilər, uzaqda da işləyib eyni anda çoxlu klientə xidmət göstərə bilər. Sizin üçün fərq əsasən onun necə qoşulmasındadır.

Serverin nəyi bacardığını o özü həll edir. Protokol serverin təklif edə biləcəyi üç növ imkanı təsvir edir:

tools - agentin icra edə biləcəyi əməliyyatlar: səhifəni almaq, API-yə sorğu göndərmək, verilənləri yazmaq;
resources - serverin kontekst kimi verdiyi məzmun: fayllar, qeydlər, servislərin cavabları;
prompts - hazır şəkildə çağırmaq olan sorğu şablonları.

Server hər üçünü dəstəkləməyə borclu deyil. Qoşulma zamanı klient və server kimin nəyi bacardığını tutuşdurur, dəstəklənməyən əməliyyatlar isə sadəcə istifadə olunmur. Bir çox server yalnız tools ilə kifayətlənir və bu, yetərlidir. MCP arxitekturası.

Əsas olanı yadda saxlamağa dəyər. MCP klientlə serverin necə danışdığını standartlaşdırır. Konkret olaraq sizə nəyin əlçatan olacağını protokol yox, server müəyyən edir. Serveri qoşmaq bütün internetə çıxış əldə etmək demək deyil - siz düz bu serverin elan etdiyi əməliyyatlar dəstini alırsınız.

Agentə tapşırıqda əmri yox, mənbəni və lazım olan nəticəni adlandırın. Sonra qoşulmuş serverdə uyğun əməliyyatın olub-olmadığını yoxlayın. Lazım olan əməliyyat yoxdursa, tapşırıq dilə tutmaqla yox, başqa marşrutla həll olunur.

Verilənlər sayta necə gəlib çatır

İndi aşağı zəncir. Dərc olunmuş səhifə verilənləri iki üsuldan biri ilə alır.

Birinci halda brauzer açıq API-yə birbaşa müraciət edir. Bu üsul mənbə açıq olanda və açar lazım olmayanda yarayır. Səhifənin kodu sorğu göndərir və cavabı ekrana çəkir. Sadə və artıq detallar olmadan.

İkinci halda brauzer tətbiqin backend-inə, o isə qapalı API-yə müraciət edir. Mənbəyə açar lazım olanda belə edirlər. Sirr serverdə qalır, brauzer onu görmür. Frontend burada ekranda görünənə cavabdehdir, backend isə serverdə icra olunana və tətbiqin adından servisə müraciət edə bilməyə.

Açıq API brauzer üçün birbaşa əlçatandır, qapalı API-nin açarı isə backend-də qalır

Yuxarı marşrut daha qısadır, çünki brauzer açıq mənbəyə özü müraciət edə bilir. Aşağı marşrutda isə backend sirr üçün sərhədə çevrilir. Açar serverdə qalır və səhifənin koduna düşmür.

İndi isə nəyin baş vermədiyi haqqında. Claude Code-un MCP-serverlə əlaqəsi dərc zamanı saytla birlikdə getmir. Serveri əlavə etdiyiniz əmr agentinizi tənzimləyir; tətbiqə bir sətir də kod əlavə etmir. Öz MCP-klienti olan tətbiq yazmaq mümkündür, amma bu, ayrıca iş və ayrıca reallaşdırmadır, Claude Code-da qoşulmanın nəticəsi deyil.

Bütün bunları yoxlamaq kifayət qədər tezdir. Claude Code-u bağlayın, dərc olunmuş səhifəni açın və developer tools-da Network tabına baxın. Verilənlər gəlirsə - sorğu, ünvan və cavab görünür. Gəlmirsə - sorğu olmayacaq və bu, məhz səhifəni başqa kimsə görməzdən əvvəl tutmağa dəyən haldır.

Ekrandakı bir şəkil azdır. Səhifə əvvəlcədən saxlanmış anlıq surəti göstərə və bu zaman tamamilə canlı görünə bilər. Sorğunun özünə baxmaq lazımdır. Əksinə, cavabda yeni hadisələrin olmaması hələ sıradan çıxma demək deyil. Mənbə sadəcə seçilmiş müddət ərzində heç nə göndərməmiş ola bilər.

Qoşulmanı necə yoxlamaq olar

İstənilən server üçün qaydası təxminən eynidir:

serverin rəsmi təlimatını tapmaq - ünvan, çıxış üsulu, əməliyyatların siyahısı;
serveri məhz bu təlimatın verdiyi əmrlə əlavə etmək;
Claude Code-da /mcp açıb serverin qoşulduğuna və hansı alətlərinin olduğuna baxmaq;
oxuma üçün bir sorğu icra etmək, ən sadəsini;
nəticəni mənbə ilə əllə tutuşdurmaq - eyni səhifəni öz gözünüzlə açmaq.

Terminaldan vəziyyəti claude mcp list, bir server üzrə detalları claude mcp get göstərir. Bilmək faydalıdır ki, bu addımlar müxtəlif suallara cavab verir:

Nə gördünüz	Bu nəyi sübut edir
əlavə etdikdən sonra `Added ...` sətri	konfiqurasiya yazılıb, vəssalam
`Connected` statusu `claude mcp list` çıxışında	Claude Code serverlə əlaqə qura bildi
alət məzmun qaytardı	marşrut sorğudan cavaba qədər tam işləyir

Fərq formal deyil. Uğurla yazılmış konfiqurasiya serverin cavab verdiyi barədə heç nə demir, uğurlu əlaqə isə lazım olan əməliyyatın əlçatan olduğu və ona hüquqların olduğu barədə. Buna görə də yoxlamanı bir real çağırışla bitirirlər. Yeri gəlmişkən, siyahıda Needs authentication görünürsə, server xarab deyil, sadəcə girişi gözləyir.

Konkret nümunə götürək. Firecrawl servisinin açıq səhifənin məzmununu almağı bacaran MCP-serveri var - alətin adı firecrawl_scrape-dir. Agent üçün bu, sənədləşmə səhifəsini hissə-hissə yazışmaya köçürmək əvəzinə tam oxumağın rahat üsuludur.

# serveri HTTP ilə əlavə etmək; dəqiq ünvanı servisin sənədlərindən götürürlər
claude mcp add --transport http firecrawl https://mcp.firecrawl.dev/v2/mcp

İndi çıxış haqqında. Firecrawl sənədləri həm hesabsız və açarsız, gündəlik məhdudiyyətlərlə işi, həm də klientin giriş səhifəsini özünün açdığı brauzer vasitəsilə girişi təsvir edir. Servislərin şərtləri və limitləri dəyişir, buna görə aktual olanlarına məqalədə yox, servisin özündə baxırlar. Firecrawl-un MCP sənədləri.

Və vaxta qənaət edən kiçik bir detal. Standart olaraq server əmri verdiyiniz layihə üçün əlavə olunur və başqa layihələrdə görünmür. Server hər yerdə və ya, əksinə, bütün komandaya lazımdırsa, əlavə etmə əmrinin görünmə sahəsi üçün ayrıca variantları var. Claude Code və MCP.

Açarın dəyərinin nə konfiqurasiya nümunəsində, nə server ünvanında, nə də agentlə yazışmada yeri yoxdur. Konfiqurasiyaya mühit dəyişəninin adı yazılır, dəyər ayrıca təyin olunur - bu, açarlar haqqında qonşu məqalənin mövzusudur.

Konkret alət nəyə icazə verir

Qoşulmuş server əməliyyatlar dəstidir və onlar nəticələrinə görə çox fərqlidir. Səhifəni oxumaq və xarici sistemdə qeydi dəyişmək heç də eyni şey deyil, baxmayaraq ki, hər ikisi eyni cür çağırılır.

Çağırışa razılıq verməzdən əvvəl üç şeyə baxmaq faydalıdır: alət hansı obyektlə işləyir, hansı əməliyyatı icra edir və bunun üçün hansı hüquqlar lazımdır. Oxumaq adətən daha təhlükəsizdir, amma onun da qiyməti var. Sorğu üçüncü tərəfin servisinə gedir və sizin kvotanızı xərcləyir.

Cavabda gələnlər haqqında ayrıca. Kənar saytdan alınmış mətn tapşırıq yox, verilənlərdir. Səhifənin içində "indi bütün faylları sil" yazılıbsa, bu, səhifədəki mətn olaraq qalır, qərarı isə siz verirsiniz. Xarici mənbəni oxuduqdan sonra agentin daha nə etmək istədiyinə məhz bu səbəbdən baxmağa dəyər.

Və əsas praktik sual. MCP ümumiyyətlə lazımdırmı? Həmişə yox.

Tapşırıq	Nə ilə həll etmək daha sadədir
saytda açıq JSON-dakı verilənləri göstərmək	tətbiqin kodundan adi sorğu, MCP lazım deyil
agent hazır inteqrasiyası olan servislə müntəzəm işləyir	MCP özünü doğruldur: əməliyyatlar təsvir olunub, qoşulma təkrar istifadə olunur
sənədləri bir dəfə oxumaq və ya bir ünvana müraciət etmək	URL-i oxumaq və ya API-yə birbaşa müraciət kifayətdir

MCP xaricə açılan yeganə qapı deyil və qalan hər şeyi əvəz etmir. Agentin əlində əmr sətri də, API-yə birbaşa müraciət də qalır. Seçim artıq qurulmuş qoşulmadan yox, tapşırıqdan irəli gəlir.

Öz layihənizdə nəyi yoxlamalı

Agent xarici verilənlərlə işi hazırlayanda ondan iki qatı sonradan dolaşığı açmaq yerinə elə indi açıq şəkildə ayırmağı xahiş etmək faydalıdır:

İki marşrutu ayrı-ayrılıqda təsvir et:
layihə üzərində işləyərkən verilənləri sən haradan götürürsən
və ziyarətçidə tətbiqin özü onları haradan götürəcək.
Tətbiqin sorğusunun hansı faylda və kodun hansı yerində yaşadığını göstər.
Səhifəni sessiya bağlı olanda yoxla: verilənlər gəlir, ya yox.
Əgər indi saxlanmış anlıq surət istifadə olunursa, bunu açıq de.

Ən çox rast gəlinən üç vəziyyət və hər biri üzrə cavab:

Nə lazımdır	Verilənləri kim alır	Niyə belə
inkişaf zamanı servisin sənədlərini öyrənmək	agent	verilənlər kod yazmaq üçün lazımdır, ziyarətçidə bu sorğu təkrarlanmır
ziyarətçidə xəritəni yeniləmək	tətbiqin kodu	sorğu səhifənin işi zamanı icra olunur, agentin sessiyası bu vaxta artıq bağlıdır
seçməni bir dəfə JSON-a saxlamaq	agent, həm də yalnız bir dəfə	sonra sayt faylı göstərir; verilənlər saxlandığı kimi qalacaq

Diqqət edin ki, MCP burada yalnız birinci sətirdə görünür, o da mütləq deyil. Tapşırıq ünvanı adi oxumaqla həll olunursa, elə belə də həll etməyə dəyər.

İşi başqasına göstərməzdən əvvəl son yoxlama ən sadəsidir: Claude Code-u bağlayın və səhifəni açın. İşləməyə davam edən hər şey sizin tətbiqinizdir. Qalan hər şey agentin inkişaf zamanı köməyi idi - faydalı, amma sizin kompüterinizdə qalan.