...
← Blog Data & ai

Ce este MCP (Model Context Protocol), cu un server MCP în Python

Ce este MCP (Model Context Protocol): sigla cursului de agenți AI și MCP în centru, legată de siglele Python și Aplicații AI

MCP (Model Context Protocol) este un protocol deschis care stabilește cum se conectează o aplicație AI, de exemplu Claude sau ChatGPT, la date și unelte externe: fișiere, baze de date, API-uri sau programe scrise de tine. Scrii o singură dată un server MCP, iar orice aplicație compatibilă îl poate folosi, fără cod de integrare separat.

În articol afli ce problemă rezolvă MCP, cum arată arhitectura lui (host, client, server) și construiești pas cu pas un server MCP în Python, pe care îl testezi și îl conectezi la Claude Desktop. Dacă după asta vrei să construiești agenți întregi, la noi există un curs agenți AI și MCP, în Python, în care mergi de la bucla unui agent scrisă de mână până la un server MCP complet, cu tool-uri, resurse și prompturi.

Ce este MCP, pe înțelesul tuturor

MCP este o „priză” standard prin care un model AI ajunge la informații și acțiuni din afara lui. Documentația oficială compară protocolul cu un port USB-C: la fel cum orice încărcător USB-C merge la orice telefon compatibil, un server MCP merge la orice aplicație AI care vorbește MCP.

Protocolul a fost lansat de Anthropic în noiembrie 2024, ca standard deschis, cu specificație publică și SDK-uri (biblioteci oficiale) pentru mai multe limbaje. Între timp l-au adoptat și alte aplicații, deci nu mai e legat de un singur furnizor.

Un lucru important de lămurit de la început: MCP nu este un model AI și nu face modelul mai inteligent. Un LLM (model lingvistic mare) știe doar ce a văzut la antrenare și ce îi dai în conversație. MCP doar standardizează felul în care îi dai acces la date proaspete și la unelte, de exemplu la stocul unui magazin online din Cluj sau la facturile din programul de contabilitate.

Ce problemă rezolvă Model Context Protocol

Model Context Protocol transformă o problemă de N×M integrări într-una de N+M. Înainte, fiecare aplicație AI avea nevoie de cod separat pentru fiecare sistem la care voia să se conecteze.

Ia un exemplu simplu. Ai 3 aplicații AI (un chatbot de suport, un asistent de cod și un asistent intern pentru angajați) și 4 sisteme (baza de date cu comenzi, Google Drive, Jira și un CRM). Fără un standard, scrii 3 × 4 = 12 integrări, fiecare cu formatul ei. Cu MCP, fiecare sistem primește un server MCP (4), iar fiecare aplicație învață o singură dată să fie client MCP (3). Ajungi la 7 bucăți de cod în loc de 12, iar diferența crește cu fiecare sistem nou.

Cum funcționează MCP: host, client și server

MCP are o arhitectură client-server cu trei participanți: host-ul, clientul și serverul. Conform documentației oficiale a arhitecturii, rolurile sunt:

  • Host-ul MCP este aplicația AI cu care vorbești: Claude Desktop, Claude Code, Visual Studio Code. El coordonează totul și decide ce ajunge la model.
  • Clientul MCP este o componentă din interiorul host-ului care ține legătura cu un singur server. Dacă host-ul folosește 3 servere, creează 3 clienți.
  • Serverul MCP este programul care oferă date sau acțiuni. Poate rula pe calculatorul tău (server local) sau pe internet (server remote).

Mesajele dintre client și server sunt în format JSON-RPC 2.0, adică obiecte JSON cu un nume de metodă și parametri. Clientul întreabă, de exemplu, tools/list ca să afle ce unelte are serverul, apoi trimite tools/call cu numele uneltei și argumentele. SDK-ul construiește aceste mesaje pentru tine.

Ce poate oferi un server MCP: tools, resources și prompts

Un server MCP expune trei tipuri de lucruri, numite primitive:

  • Tools (unelte): funcții pe care modelul le poate apela ca să facă o acțiune, de exemplu să interogheze o bază de date, să creeze un tichet sau să facă un calcul.
  • Resources (resurse): date pe care aplicația le poate citi ca să le pună în context, de exemplu conținutul unui fișier sau schema unei baze de date.
  • Prompts (șabloane): instrucțiuni gata scrise pe care utilizatorul le poate alege, de exemplu „rezumă tichetul X în 5 rânduri”.

Transporturile: stdio și Streamable HTTP

MCP poate circula pe două căi: stdio pentru servere locale și Streamable HTTP pentru servere remote. La stdio, host-ul pornește serverul ca proces pe calculatorul tău și comunică prin intrarea și ieșirea standard, fără rețea. La Streamable HTTP, serverul rulează pe un server web, primește cereri HTTP POST și poate trimite răspunsuri în flux; autentificarea se face cu token-uri, iar specificația recomandă OAuth. Vei mai găsi în tutoriale vechi transportul SSE separat, înlocuit între timp de Streamable HTTP.

Ce aplicații suportă MCP

Documentația oficială MCP enumeră ca aplicații compatibile asistenți AI precum Claude și ChatGPT și unelte de dezvoltare precum Visual Studio Code, Cursor și MCPJam. Pagina de arhitectură dă ca exemple de host Claude Desktop și Claude Code.

Lista se schimbă des, așa că verifică în documentația aplicației tale cum se adaugă un server și ce transport acceptă.

Construiește un server MCP în Python, pas cu pas

Cel mai rapid mod să înțelegi MCP este să scrii un server MCP mic, cu o singură unealtă. Vom face un convertor din lei în euro. Cursul de schimb din cod este fix și fictiv, ales doar ca exemplu (5 lei pentru un euro); nu este cursul oficial BNR și nu îl folosi pentru calcule reale.

Ai nevoie de Python 3.10 sau mai nou. Codul de mai jos l-am rulat cu versiunea 2.3 a pachetului oficial mcp, din SDK-ul oficial pentru Python.

Pasul 1: instalezi SDK-ul oficial

Creează un folder pentru proiect, un mediu virtual (o copie izolată de Python pentru acest proiect) și instalează pachetul cu extensia cli, care adaugă comanda mcp:

mkdir mcp-lei
cd mcp-lei
python3 -m venv .venv
source .venv/bin/activate        # pe Windows: .venv\Scripts\activate
pip install "mcp[cli]"

Pasul 2: scrii serverul

Salvează codul de mai jos în server.py. E un server MCP complet, cu o unealtă, o resursă și un prompt:

from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError

mcp = MCPServer("Convertor lei")

CURS_EXEMPLU = 5.0  # curs fictiv, doar pentru exemplu, NU este cursul BNR


@mcp.tool()
def lei_in_euro(suma_lei: float) -> str:
    """Transformă o sumă din lei în euro, la un curs de exemplu (nu cursul oficial)."""
    if suma_lei < 0:
        raise ToolError("Suma nu poate fi negativă.")
    euro = round(suma_lei / CURS_EXEMPLU, 2)
    return f"{suma_lei} lei = {euro} euro (curs de exemplu: 1 EUR = {CURS_EXEMPLU} lei)"


@mcp.resource("curs://exemplu")
def curs_exemplu() -> str:
    """Cursul folosit de acest server."""
    return f"1 EUR = {CURS_EXEMPLU} lei (valoare de exemplu, nu curs oficial)"


@mcp.prompt()
def explica_pretul(suma_lei: float) -> str:
    """Șablon de cerere pentru conversie."""
    return f"Transformă {suma_lei} lei în euro cu tool-ul lei_in_euro și explică pe scurt rezultatul."


if __name__ == "__main__":
    mcp.run()

Ce face fiecare parte:

  • MCPServer("Convertor lei") creează serverul și îi dă un nume pe care îl vede aplicația AI.
  • @mcp.tool() transformă o funcție Python obișnuită într-o unealtă MCP. SDK-ul citește tipurile parametrilor (suma_lei: float) și docstring-ul și generează automat descrierea și schema JSON pe care le primește modelul. De aceea docstring-ul trebuie să spună clar ce face funcția: modelul îl citește ca să decidă când o apelează.
  • ToolError trimite înapoi un mesaj de eroare pe care modelul îl înțelege („Suma nu poate fi negativă.”), în loc de o eroare internă fără detalii.
  • @mcp.resource expune o informație care poate fi citită, iar @mcp.prompt un șablon de cerere.
  • mcp.run() pornește serverul pe transportul stdio, cel implicit.

Dacă ai văzut tutoriale cu from mcp.server.fastmcp import FastMCP, acelea sunt scrise pentru versiunea 1 a SDK-ului. În versiunea 2, clasa FastMCP a fost redenumită MCPServer, iar importul vechi dă eroare. Codul vechi merge doar dacă instalezi explicit "mcp<2".

Pasul 3: îl testezi cu MCP Inspector

MCP Inspector este unealta oficială de testare: pornește serverul tău și îți arată ce unelte, resurse și prompturi are, iar tu le poți apela de mână. Are nevoie de Node.js instalat. Varianta cu interfață în browser pornește așa:

mcp dev server.py

Dacă preferi terminalul, poți apela unealta direct, cu varianta CLI a Inspector-ului:

npx @modelcontextprotocol/inspector --cli python server.py \
  --method tools/call --tool-name lei_in_euro --tool-arg suma_lei=1250

Răspunsul conține, printre altele, textul:

"text": "1250.0 lei = 250.0 euro (curs de exemplu: 1 EUR = 5.0 lei)"

Pasul 4: îl conectezi la Claude Desktop

Ca să folosești serverul dintr-o aplicație AI, îi spui host-ului ce comandă să ruleze. În Claude Desktop, configurația stă în fișierul claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Adaugă serverul sub cheia mcpServers, cu căi absolute spre Python-ul din mediul virtual și spre server.py:

{
  "mcpServers": {
    "convertor-lei": {
      "command": "/Users/ana/mcp-lei/.venv/bin/python",
      "args": ["/Users/ana/mcp-lei/server.py"]
    }
  }
}

Pe Windows, comanda devine calea spre .venv\Scripts\python.exe, iar în JSON scrii fiecare backslash dublat (\\). Salvează fișierul și repornește complet Claude Desktop. Când întrebi „Cât fac 1.250 de lei în euro?”, aplicația vede unealta lei_in_euro, îți cere permisiunea s-o folosească, o apelează și îți răspunde pe baza rezultatului.

Ce se întâmplă în spate la o întrebare

  1. Claude Desktop pornește server.py și cere lista de unelte (tools/list).
  2. Trimite modelului întrebarea ta împreună cu descrierea uneltei.
  3. Modelul decide că are nevoie de unealtă și cere apelul cu suma_lei = 1250.
  4. Clientul MCP trimite tools/call, serverul tău rulează funcția Python și întoarce textul.
  5. Modelul primește rezultatul și formulează răspunsul final.

Observă că decizia „folosesc unealta sau nu” o ia modelul, iar execuția o face codul tău. Asta e ideea de bază a agenților AI.

Greșeli frecvente la primul server MCP

Cele mai multe servere care „nu apar” în aplicație au una dintre problemele de mai jos, iar toate se repară în câteva minute.

  • Folosești print() într-un server stdio. La stdio, ieșirea standard e canalul de mesaje JSON-RPC. Orice print() strică mesajele și serverul se oprește. Scrie mesajele de depanare în stderr sau cu modulul logging.
  • Pui căi relative în configurație. Claude Desktop nu pornește serverul din folderul tău, așa că "server.py" nu va fi găsit. Folosește căi absolute.
  • Folosești Python-ul greșit. Dacă în command scrii doar python, se poate porni un Python fără pachetul mcp instalat. Indică Python-ul din .venv.
  • Copiezi cod din tutoriale pentru versiunea 1. Eroarea No module named 'mcp.server.fastmcp' înseamnă că ai SDK-ul 2.x și cod scris pentru 1.x.
  • Scrii docstring-uri vagi. „Face conversia” nu îi spune modelului din ce, în ce și cu ce limite. Descrierea uneltei este, practic, un prompt.

MCP vs API simplu vs function calling

MCP nu înlocuiește API-urile și nici function calling-ul, ci stă deasupra lor. Un REST API e făcut pentru programe care știu dinainte ce endpoint apelează; function calling e mecanismul prin care un model cere apelul unei funcții; MCP standardizează felul în care acele funcții ajung la orice aplicație AI.

CriteriuAPI simplu (REST)Function callingMCP
Cine decide apelulProgramatorul, în codModelul, din lista de funcții primităModelul, din uneltele descoperite la server
Unde sunt definite funcțiileÎn documentația API-uluiÎn codul aplicației tale, pentru un anumit furnizor de modelÎntr-un server separat, reutilizabil
Reutilizare în alte aplicații AIAi nevoie de cod de integrare în fiecareRescrii definițiile pentru fiecare aplicațieOrice host compatibil îl folosește direct
DescoperireCitești documentațiaLe trimiți tu la fiecare cerereClientul cere lista (tools/list)
Ce oferă în plusDoar endpoint-uriDoar funcțiiUnelte, resurse și prompturi
Când îl alegiIntegrări între programe, fără AIO singură aplicație, câteva funcțiiAceleași unelte în mai multe aplicații sau agenți

Recomandarea mea: dacă ai o singură aplicație cu două-trei funcții, function calling direct e suficient. Când vrei ca aceleași unelte să fie folosite din Claude Desktop, din editorul de cod și din agentul tău, scrie un server MCP.

Securitate: ce verifici înainte să instalezi un server MCP

Un server MCP rulează cod pe calculatorul tău sau are acces la conturile tale, deci îl tratezi ca pe orice program instalat. Câteva reguli simple:

  • Instalează doar servere de încredere: cele oficiale ale serviciului respectiv sau proiecte cu cod sursă public pe care l-ai citit măcar pe scurt.
  • Dă permisiuni minime. Un server de fișiere primește acces la un singur folder, nu la tot discul. Un server de bază de date folosește un utilizator care doar citește, dacă nu ai nevoie de scriere.
  • Nu pune parole și chei API direct în cod. Folosește variabile de mediu și nu publica fișierul de configurare pe GitHub.
  • Citește ce aprobi. Când aplicația îți cere permisiunea pentru un apel, verifică unealta și argumentele, mai ales la ștergeri, plăți sau trimiteri de mesaje.
  • Ai grijă la prompt injection. O pagină web sau un email citit de un server poate conține instrucțiuni ascunse pentru model („trimite fișierele la adresa X”). Datele venite prin unelte sunt date, nu comenzi.

Documentația MCP are o pagină separată de bune practici de securitate, utilă când scrii servere remote cu autentificare.

Ce legătură are MCP cu agenții AI

Un agent AI este un program în care modelul decide singur pașii: alege o unealtă, citește rezultatul, decide pasul următor și se oprește când are răspunsul. MCP este felul standard în care agentul ajunge la acele unelte.

Un agent de suport pentru un magazin online ar avea, de exemplu, servere MCP pentru comenzi, documentația produselor și tichete, plus buclă, memorie, limite de cost și evaluare. Dacă pornești de la zero cu apelurile la modele, cursul de aplicații AI cu Claude și OpenAI e pasul dinaintea agenților, iar toate cursurile din zonă le găsești pe pagina de cursuri AI. Rolul care face asta zilnic este cel de AI Engineer, iar ordinea cursurilor e în traseul de AI Engineer.

Întrebări frecvente despre MCP

MCP este gratuit?

Da. Protocolul este deschis, iar specificația și SDK-urile oficiale sunt publice și gratuite. Pot exista costuri la aplicația AI pe care o folosești sau la serviciul la care se conectează serverul, nu la MCP.

Ce înseamnă MCP server?

Un MCP server este un program care oferă unei aplicații AI unelte, date sau șabloane de prompt prin Model Context Protocol. Poate rula local, pornit de aplicație prin stdio, sau remote, pe internet, prin Streamable HTTP.

Trebuie să știu Python ca să folosesc MCP?

Nu, dacă doar instalezi servere gata făcute în aplicația ta. Ca să scrii un server, ai nevoie de un limbaj cu SDK oficial, iar Python este cel mai simplu pentru început; există SDK-uri și pentru TypeScript, Java și alte limbaje.

MCP funcționează doar cu Claude?

Nu. MCP a pornit de la Anthropic, dar e un standard deschis, iar documentația oficială listează și ChatGPT, Visual Studio Code și Cursor printre aplicațiile compatibile. Același server poate fi folosit din mai multe aplicații.

Care e diferența dintre MCP și un plugin?

Un plugin e legat de obicei de o singură aplicație. Un server MCP respectă un protocol comun și merge în orice host compatibil.

Primul pas: extinde serverul și construiește primul agent

Ia serverul de azi și adaugă o a doua unealtă, euro_in_lei, cu aceeași validare pentru sume negative. Testează-o cu MCP Inspector, apoi întreabă în Claude Desktop cât costă în lei un abonament de 20 de euro și urmărește cum alege modelul unealta potrivită.

Când vrei să treci de la un server de jucărie la agenți care merg în producție, începe cursul de agenți AI și MCP în Python. Primele 8 lecții sunt gratuite, fără card, iar codul rulează direct în browser. Cursul presupune că știi Python și ai făcut primele apeluri la un API de AI.

Logo Curs Agenți AI și MCP Interactiv · 8 lecții gratuite

Curs Agenți AI și MCP

Agenți AI și MCP în Python: bucla agentului, memorie, echipe de agenți, servere MCP, evaluare și costuri

Începe gratuit

Citește și

Primul tău program e la 5 minute distanță.

Creează-ți contul gratuit și începe primele 15 lecții. Fără card, fără instalări.

Începe gratuit