Cum să construiești un server MCP: Tutorial pas cu pas în Python și TypeScript (2026)

Poți construi un server MCP pe care Claude îl apelează efectiv în aproximativ 15 minute. Am cronometrat procesul pe Node 20 și Python 3.11: un instrument add funcțional, rulând prin stdio, detectat de Claude Desktop, a luat 14 minute la prima încercare și sub 5 minute odată ce înțelegi structura. Acest tutorial construiește același server de două ori, o dată în Python cu FastMCP 2.x, o dată în TypeScript cu @modelcontextprotocol/sdk 1.x — astfel încât să poți alege stiva tehnologică preferată și să copiezi cod real. Dacă dorești mai întâi arhitectura și teoria protocolului, ghidul nostru de concepte Model Context Protocol le conține; aici ne concentrăm doar pe construcție.

Pornire rapidă server MCP: Ce construiești

Un server MCP este un program mic care expune instrumente, date și șabloane de prompt către clienți AI precum Claude, Cursor sau VS Code prin intermediul Model Context Protocol. Scrii serverul o singură dată, iar orice client compatibil MCP îl poate apela. În acest tutorial vei construi un server cu două instrumente (un calculator add și un helper fetch_url), îl vei rula local prin stdio, îl vei testa și îl vei conecta la un client real.

Iată tot ce ai nevoie înainte de a începe.

Ambele căi produc un server care se comportă identic. Alege limbajul pe care echipa ta îl folosește deja în producție. Dacă nu ai o preferință, începe cu Python, deoarece FastMCP face ca primul server să fie mai concis.

Ce expune de fapt un server MCP?

Înainte de a scrie cod, este util să cunoști cele trei lucruri pe care un server le poate oferi. Un server MCP expune instrumente (funcții pe care modelul le poate apela, cum ar fi „caută în baza de date”), resurse (date read-only pe care modelul le poate încărca, cum ar fi un fișier sau o înregistrare) și prompturi (șabloane de prompt reutilizabile). Majoritatea serverelor pe care le vei construi vor fi concentrate pe instrumente; resursele și prompturile sunt opționale.

Server MCP, definit: un proces care vorbește Model Context Protocol și anunță o listă de instrumente, resurse și prompturi pe care un client AI le poate descoperi și invoca la runtime.

Clientul (de exemplu, Claude Desktop) acționează ca gazdă. Acesta lansează sau se conectează la serverul tău, întreabă „ce instrumente ai?” și apoi le apelează atunci când modelul decide că un instrument este util. Nu apelezi niciodată modelul din interiorul serverului. Fluxul rulează în sens invers.

Această direcție contează. Serverul tău este un furnizor pasiv. Așteaptă ca clientul să se conecteze, răspunde la cererea de descoperire și execută orice instrument este apelat. Păstrează acest model mental și restul acestui tutorial va deveni clar.

Cum să construiești un server MCP în Python (Pas cu pas)

Python este cea mai rapidă cale către un server funcțional deoarece FastMCP gestionează complexitatea protocolului și transformă funcțiile simple în instrumente printr-un decorator. Tot ce urmează folosește SDK-ul oficial Python. Iată cei patru pași.

Pasul 1: Configurează proiectul. Folosește uv, care este acum standardul pentru proiectele MCP Python:

uv init mcp-demo
cd mcp-demo
uv add "mcp[cli]"

Dacă preferi pip: python -m venv .venv && source .venv/bin/activate && pip install "mcp[cli]".

Pasul 2: Scrie serverul. Creează server.py:

from mcp.server.fastmcp import FastMCP
import httpx

# Name shows up in the client's tool list
mcp = FastMCP("demo-server")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers and return the sum."""
    return a + b

@mcp.tool()
async def fetch_url(url: str) -> str:
    """Fetch a URL and return the first 2000 characters of the body."""
    async with httpx.AsyncClient(timeout=10) as client:
        resp = await client.get(url)
        return resp.text[:2000]

if __name__ == "__main__":
    mcp.run()  # defaults to stdio transport

Două aspecte de remarcat. Docstring-ul devine descrierea instrumentului citită de model, așa că scrie-l ca pe o instrucțiune. Iar hint-urile de tip (a: int) devin schema de intrare automat, astfel încât FastMCP generează JSON Schema pentru tine.

Pasul 3: Rulează-l. mcp.run() pornește serverul pe stdio, transportul pe care clienții îl lansează local. Nu rulezi acest lucru direct în timpul dezvoltării; clientul îl lansează. Pentru un test rapid de funcționare, folosește runner-ul de dezvoltare:

uv run mcp dev server.py

Pasul 4: Returnează un output curat. O capcană worth menționată acum: returnează un șir de caractere sau o valoare tipată, nu un dict imbricat brut pe care speri că se va randiza corect. Vom reveni asupra motivului în secțiunea de producție, dar pe scurt, tipurile de returnare ambigue pot fi trunchiate silențios în unele clienți.

Acesta este un server MCP Python complet. Două instrumente, apeluri de rețea reale, schemă automată. Mai departe, același lucru în TypeScript.

Cum să construiești un server MCP în TypeScript (Pas cu pas)

Calea TypeScript folosește direct SDK-ul oficial TypeScript și zod pentru validarea input-ului. Este puțin mai verbose decât FastMCP, dar tipurile sunt excelente și se implementează curat pe host-uri Node.

Pasul 1: Configurează proiectul.

mkdir mcp-demo && cd mcp-demo
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx

Pasul 2: Scrie serverul. Creează server.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "demo-server", version: "1.0.0" });

server.tool(
  "add",
  "Add two numbers and return the sum.",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
  }),
);

server.tool(
  "fetch_url",
  "Fetch a URL and return the first 2000 characters.",
  { url: z.string().url() },
  async ({ url }) => {
    const resp = await fetch(url);
    const body = await resp.text();
    return { content: [{ type: "text", text: body.slice(0, 2000) }] };
  },
);

const transport = new StdioServerTransport();
await server.connect(transport);

Pasul 3: Rulează-l. În timpul dezvoltării: npx tsx server.ts. Pentru producție, compilează cu tsc și rulează fișierul .js construit cu Node. Observă forma returnată: fiecare instrument returnează { content: [{ type: "text", text: ... }] }. Acest array explicit content este echivalentul TypeScript al regulii „returnează un șir curat” din Python. SDK-ul dorește blocuri de conținut tipate, nu obiecte brute.

Pasul 4: Validează input-urile cu zod. Schema z.string().url() respinge input-ul incorect înainte ca handler-ul tău să ruleze, ceea este exact ceea ce îți dorești atunci când un model generează argumentele.

Aceleași două instrumente, același comportament, TypeScript idiomatic. Acum să decidem cum ar trebui clienții să acceseze serverul tău.

stdio vs Streamable HTTP: Ce transport ar trebui să folosești?

Serverele MCP comunică prin unul dintre două transporturi. stdio rulează serverul ca un subprocess local pe care clientul îl lansează și cu care comunică prin intrarea/ieșirea standard. Streamable HTTP rulează serverul ca un serviciu de rețea la care clienții se conectează prin HTTP. Alege în funcție de locul unde trebuie să reside serverul.

Regula de bază: construiește și testează pe stdio, apoi treci la Streamable HTTP doar când mai mult de o persoană sau mașină are nevoie de server. Majoritatea serverelor nu trebuie să părăsească niciodată stdio. Apelurile mcp.run() și StdioServerTransport() de mai sus sunt deja stdio, deci ești pregătit pentru dezvoltare.

Cum să testezi serverul tău MCP cu Inspector

Înainte de a integra serverul în Claude, testează-l izolat cu MCP Inspector. Este o interfață browser care se conectează la serverul tău, listează instrumentele sale și îți permite să le apelezi manual. Rulează-l împotriva serverului tău:

# Python
npx @modelcontextprotocol/inspector uv run server.py
# TypeScript
npx @modelcontextprotocol/inspector npx tsx server.ts

Inspectorul deschide o pagină locală unde poți vedea instrumentele tale add și fetch_url, poți lansa un apel de test și poți citi răspunsul brut. Aceasta este cea mai bună practică pentru dezvoltarea MCP. Dacă schema unui instrument este malformată sau o valoare returnată este greșită, vei vedea aici în câteva secunde, în loc să te uiți la o eroare silențioasă în interiorul Claude. Am prins astfel o schemă de input defectuoasă care altfel ar fi costat un ciclu complet de debug prin client. Testează în Inspector mai întâi, de fiecare dată.

Cum să conectezi serverul tău MCP la Claude Desktop, Claude Code și Cursor

Odată ce Inspectorul este mulțumit, îndreaptă un client real către serverul tău. Fiecare client citește un fișier de configurare care îi spune cum să lanseze serverul tău prin stdio.

Claude Desktop. Editează claude_desktop_config.json (pe macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "demo-server": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/mcp-demo", "run", "server.py"]
    }
  }
}

Restartează Claude Desktop și instrumentele tale vor apărea sub iconița conectorilor.

Claude Code. Adaugă serverul cu o singură comandă din proiectul tău: claude mcp add demo-server -- uv run server.py. Claude Code îl stochează în configurația proiectului și îl încarcă la lansare. Dacă folosești și hook-uri pentru a scripta Claude Code, ghidul nostru de hook-uri Claude Code se potrivește bine cu instrumentele MCP personalizate.

Cursor. Adaugă același bloc mcpServers în .cursor/mcp.json în rădăcina proiectului tău. Structura se potrivește cu cea a Claude Desktop. Pentru un exemplu din lumea reală al unui server MCP care rulează în interiorul Claude Code, vezi cum am integrat Higgsfield în Claude Code.

Folosește căi absolute în fiecare configurație. Căile relative sunt cel mai comun motiv pentru care un server nu reușește să pornească.

Implementarea unui server MCP în producție (Auth și Hosting)

Când serverul tău trebuie partajat, mută-l de la stdio la Streamable HTTP și adaugă trei lucruri: autentificare, gestionarea erorilor și un host.

• Autentificare. Serverele MCP remote trebuie să folosească OAuth 2.1 conform specificației de autorizare MCP. Pentru instrumente interne, o verificare bearer-token pe endpoint-ul HTTP este minimul pragmatic. Nu lansa niciodată un server de instrumente public, neautentificat, deoarece un instrument care rulează SQL sau lovește API-uri interne este o suprafață de atac activă.
• Gestionarea erorilor. Înfășoară corpurile instrumentelor în try/except (sau try/catch) și returnează un mesaj de eroare tipat în loc să arunci excepții. Modelul gestionează mult mai bine „interogarea a eșuat, iată de ce” decât o conexiune întreruptă.
• Hosting. Orice platformă care rulează un proces Node sau Python de lungă durată funcționează: un VPS mic, Fly.io, Railway sau un container pe propria infrastructură. Menține procesul „cald”, deoarece pornirile la rece adaugă latență primului apel de instrument.
• Concurență și cost. Dacă instrumentele tale apelează un LLM sau un API plătit downstream, pune un gateway în fața lor. Recenzia noastră de instrumente gateway LLM acoperă limitarea ratei și fallback-ul, iar instrumentele de inginerie a contextului ajută la prevenirea umflării ferestrei de context a modelului cu output-uri de instrumente.

Pentru Python, schimbă apelul de rulare în mcp.run(transport="streamable-http"); pentru TypeScript, înlocuiește StdioServerTransport cu StreamableHTTPServerTransport din SDK. Definițiile instrumentelor nu se schimbă deloc — acesta este scopul abstractizării transportului.

Ce am învățat lansând servere MCP în producție

Am construit servere MCP pentru uz intern la Techsy, iar câteva lecții apar doar când traficul real le lovește. Iată ce am măsurat și unde am avut probleme.

Primul server lansat a fost un instrument de interogare Postgres read-only construit cu FastMCP 2.x pe SDK-ul Python mcp 1.x, rescris ulterior în @modelcontextprotocol/sdk 1.x pentru comparație. Pe o stivă 2026 (Node 20, Python 3.11), apelurile locale de instrumente stdio au adăugat aproximativ 8 până la 12 ms overhead de transport per apel. Odată ce am mutat același server pe Streamable HTTP pe un VPS, costul per apel a crescut la 40 până la 70 ms, aproape entirely datorită dus-întorsului de rețea, nu costului protocolului. Pornirea la rece FastMCP a fost de aproximativ 300 ms pentru proces, motiv pentru care menținem procesul de producție cald.

Capcana care ne-a costat aproximativ două ore: un instrument care returna un dict Python brut se randiza bine în Inspector, dar revenea trunchiat în interiorul Claude Desktop. Înfășurarea valorii returnate ca un șir de text tipat a rezolvat problema instantaneu. De aceea acest tutorial returnează șiruri și blocuri de text content peste tot, în loc de obiecte imbricate. Cealaltă practică care a dat roade imediat a fost rularea fiecărui server prin npx @modelcontextprotocol/inspector înainte de a atinge configurația clientului, ceea ce a evidențiat o schemă de input malformată la rescrierea TypeScript care altfel ar fi eșuat silențios în Cursor.

Dacă alegi ce instrumente să construiești în servere în primul rând, lista noastră cu cele mai bune servere MCP în 2026 este o bună bancă de idei.

Cum abordează Techsy dezvoltarea MCP

La Techsy construim servere MCP ca parte a sistemelor de agenți AI pe care le livrăm pentru clienți, conectând agenții la baze de date interne, CRM-uri și API-uri printr-un strat de instrumente tipat. Abordarea noastră este să începem îngust (un instrument bine testat prin stdio), să îl validăm în Inspector, apoi să îl promovăm la un serviciu HTTP autentificat doar când mai mult de un agent are nevoie de el. Combinăm serverele personalizate cu Claude Agent SDK când logica agentului devine complexă.

Aceasta este versiunea onestă: majoritatea echipelor supra-construiesc primul lor server. Rareori ai nevoie de HTTP, OAuth și o duzină de instrumente în prima zi. Dacă dorești o a doua pereche de ochi asupra unei integrări MCP, obține o consultanță gratuită și îți vom spune dacă este o treabă de un singur instrument prin stdio sau ceva care necesită cu adevărat infrastructură.

Întrebări frecvente

Ar trebui să îmi construiesc serverul MCP în Python sau TypeScript?

Folosește oricare dintre ele pe care echipa ta îl livrează deja. Python cu FastMCP este cea mai scurtă cale către un prim server funcțional deoarece un decorator transformă o funcție într-un instrument. TypeScript cu SDK-ul oficial este puțin mai verbose, dar oferă tipuri excelente și se implementează curat pe host-uri Node. Ambele produc servere care se comportă identic pentru client.

Am nevoie de un framework precum FastMCP pentru a construi un server MCP?

Nu, dar ajută. FastMCP este inclus în SDK-ul oficial Python mcp și elimină majoritatea boilerplate-ului protocolului. Poți folosi API-ul Server de nivel inferior pentru control fin, dar pentru aproape fiecare server FastMCP (Python) sau McpServer (TypeScript) este instrumentul potrivit și necesită mult mai puțin cod.

Cum debugez un server MCP care nu funcționează?

Rulează-l mai întâi prin MCP Inspector: npx @modelcontextprotocol/inspector urmat de comanda ta de rulare. Inspectorul listează instrumentele tale și îți permite să le apelezi direct, astfel încât să poți confirma că serverul funcționează înainte de a da vina pe client. Dacă Inspectorul este în regulă, dar clientul nu, verifică dacă configurația ta folosește căi absolute și dacă ai restartat clientul.

Este FastMCP o parte oficială a MCP?

Da. FastMCP este bundled cu SDK-ul oficial Model Context Protocol Python ca interfață server de nivel înalt. Decoratorul @mcp.tool() pe care îl folosești este metoda recomandată pentru a construi servere Python, nu un add-on third-party.

Care este diferența dintre un server MCP local și unul remote?

Un server local rulează pe mașina ta prin stdio, lansat de client ca un subprocess, ideal pentru instrumente personale și dezvoltare. Un server remote rulează ca un serviciu web prin Streamable HTTP și este accesibil de mai mulți clienți, ceea ce necesită autentificare OAuth 2.1. Construiește local mai întâi, mergi remote doar când partajezi.

În ce limbaje pot construi un server MCP?

Model Context Protocol are SDK-uri oficiale pentru Python, TypeScript, Java, Kotlin și C#, cu SDK-uri community în alte limbaje. Deoarece MCP este un protocol wire, orice limbaj care poate citi și scrie JSON-RPC prin stdio sau HTTP poate implementa un server, dar SDK-urile oficiale te scutesc de această muncă.

Funcționează un server MCP cu ChatGPT și Gemini, sau doar cu Claude?

MCP este un standard open adoptat în ecosistemul AI agentic, inclusiv ChatGPT, Gemini, Cursor și VS Code Copilot. Un singur server pe care îl construiești funcționează cu orice client compatibil. Nu scrii o integrare separată per model, ceea este întregul scop al protocolului.

Cât timp durează construirea unui server MCP funcțional?

Un prim server cu unul sau două instrumente care rulează prin stdio durează aproximativ 15 minute odată ce runtime-ul este instalat. Am măsurat 14 minute pentru un începător pe Node 20 și sub 5 minute pentru o reconstrucție. Adăugarea autentificării, transportului HTTP și hosting-ului de producție este ceea ce ia timp real, nu serverul în sine.

Despre autor

Mert Batur Gurbuz este Co-Fondator al Techsy.io, unde echipa livrează agenți AI, sisteme de automatizare și pipeline-uri voice/SDR pentru clienți B2B. Studiază la University of Birmingham și scrie despre stiva de tooling LLM pe care echipa Techsy o folosește efectiv în producție. Conectează-te pe LinkedIn.

Mert Batur Gurbuz, Co-Fondator, Techsy.io, University of Birmingham