MCP servers: ghid practic pentru echipe românești care construiesc cu Claude

Model Context Protocol (MCP) e standardul deschis prin care un model de limbaj devine capabil să folosească aplicațiile tale interne, nu doar să răspundă din memorie. Pentru o echipă din România care construiește cu Claude, MCP e cea mai rapidă modalitate de a transforma un sistem intern în ceva pe care Claude îl poate folosi în Claude Desktop, Claude Code, sau direct prin API.

Ghidul ăsta tratează ce e MCP, cum proiectezi un server util, cum îl conectezi, ce capcane întâlnești, și ce am învățat construind MCP servers care dau Claude control complet de aplicații custom pentru clienții noștri.

Ce e MCP, pe scurt

MCP definește un protocol (transport JSON-RPC peste stdio sau HTTP+SSE) prin care un client (Claude Desktop, Claude Code, sau o aplicație custom construită pe Claude API) poate descoperi și folosi tools, resources, și prompts expuse de un server.

• Tools sunt funcții pe care modelul le poate apela: "creează un ticket", "interoghează baza de clienți", "trimite un email". Au input schema (validată de client), output, și o descriere care îi spune modelului când să le folosească.
• Resources sunt date pe care clientul le poate citi: fișiere, înregistrări din baze de date, conținut dinamic. Modelul le poate referenția în răspunsuri.
• Prompts sunt template-uri reutilizabile pe care clientul le poate oferi utilizatorului (de exemplu un slash command predefinit).

Diferența practică față de tool use direct prin API: un server MCP scris o singură dată funcționează în orice client compatibil. Claude Desktop îl folosește prin meniu. Claude Code îl folosește prin slash command și hooks. O aplicație custom îl folosește prin SDK. Nu rescrii pluming pentru fiecare context.

Când construiești un MCP server

Pentru organizații care lucrează cu Claude, întrebarea nu mai e "să construim un agent pentru fiecare sistem?", ci "să expunem fiecare sistem ca MCP server?". Indicatorii că un sistem merită wrappat ca MCP server:

• Are un API (REST, GraphQL, ODBC) stabil. Sau are o bază de date pe care o poți interoga.
• Mai mult de un agent sau use case ar beneficia de el.
• Vrei ca echipa de dezvoltare să folosească sistemul direct prin Claude Code (de exemplu pentru a debug-a un raport în timpul implementării).
• Vrei să oferi clienților tăi capacitatea de a vorbi cu propria aplicație prin Claude Desktop.

La Ran·AI construim MCP servers pentru clienți care dau Claude control complet de aplicații custom: navigare, citire, scriere de date, declanșare de operațiuni cu efect. Pattern-ul transferă natural către orice sistem cu un API decent.

Anatomia unui MCP server

Un server MCP scris în TypeScript (SDK oficial) arată cam așa la nivel conceptual:

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: "ticketing-internal",
  version: "1.0.0"
});

server.tool(
  "search_tickets",
  {
    description: "Caută tichete în sistemul intern cu filtre",
    inputSchema: {
      query: z.string().describe("Cuvinte cheie pentru căutare"),
      team: z.string().optional().describe("Restricție la o echipă"),
      status: z.enum(["open", "closed", "all"]).default("open")
    }
  },
  async ({ query, team, status }) => {
    const results = await ticketingApi.search({ query, team, status });
    return {
      content: results.map((t) => ({
        type: "text",
        text: `#${t.id}: ${t.title}\nStatus: ${t.status}\n${t.summary}`
      }))
    };
  }
);

server.tool(
  "create_ticket",
  {
    description: "Creează un tichet nou",
    inputSchema: {
      title: z.string(),
      description: z.string(),
      team: z.string(),
      priority: z.enum(["low", "medium", "high"]).default("medium")
    }
  },
  async (input) => {
    const ticket = await ticketingApi.create(input);
    return {
      content: [{ type: "text", text: `Tichet creat: #${ticket.id}` }]
    };
  }
);

await server.connect(new StdioServerTransport());

Câteva observații practice:

Descrierile tool-urilor contează enorm. Modelul decide când să folosească tool-ul pe baza descrierii. Scrie ca pentru un coleg nou care nu cunoaște sistemul tău. "Caută tichete" e prea vag. "Caută tichete în sistemul intern cu filtre pentru echipă și status" e specific. Adaugă exemple în descriere când contează.

Input schema cu Zod e standardul. Permite validare automată și descrieri per câmp pe care le vede modelul. Folosește describe() pe câmpuri non-evidente.

Output sub formă de content blocks. Returnează text structurat (markdown sau JSON formatat) pentru ca modelul să-l poată folosi în răspunsuri.

Conectarea la Claude Desktop și Claude Code

Claude Desktop. Pentru un server care rulează local prin stdio, adaugi intrare în ~/.../claude_desktop_config.json (locația exactă depinde de OS):

{
  "mcpServers": {
    "ticketing-internal": {
      "command": "node",
      "args": ["/path/to/server/dist/index.js"],
      "env": {
        "TICKETING_API_URL": "https://internal.company.com/api",
        "TICKETING_TOKEN": "..."
      }
    }
  }
}

Restart Claude Desktop. Tool-urile apar în UI și modelul le poate folosi în conversații.

Claude Code. Configurarea e similară, în ~/.claude/mcp.json sau în settings la nivel de proiect. Avantajul Claude Code: tool-urile MCP devin accesibile pentru subagenți și hooks, ceea ce înseamnă că un proces de dezvoltare poate folosi sistemul tău intern fără să iasă din terminal.

HTTP transport pentru servere remote. Pentru organizații care vor un server centralizat (nu o instanță per machină a fiecărui dezvoltator), MCP suportă transport HTTP cu Server-Sent Events. Serverul rulează în infrastructura ta, clientul se autentifică, iar tool-urile devin partajate.

Autentificare și securitate

Aici proiectele se sparg dacă nu te gândești de la început. Câteva principii pe care le respectăm:

Niciodată credențiale hardcodate în server. Pentru servere stdio locale, folosește variabile de mediu trecute prin config-ul clientului. Pentru servere HTTP, folosește OAuth (în 2026 SDK-urile MCP suportă PKCE) sau token-uri per-utilizator generate prin sistemul tău de identitate.

Permisiuni per utilizator, nu per server. Dacă serverul tău expune un tool "delete_record", nu toți utilizatorii care au acces la server au voie să-l apeleze. Verifică permisiunile în handler-ul tool-ului, nu doar la conectare.

Confirmare la acțiuni cu efect. Pentru tool-uri care modifică starea (creează, șterge, postează), construiește o etapă de confirmare. Claude Desktop și Claude Code permit ca tool-ul să returneze un preview pe care utilizatorul îl aprobă înainte de execuție.

Rate limiting. Un model care e într-un loop poate apela tool-ul tău de zeci de ori în câteva secunde. Pune limite per sesiune pentru protejarea sistemului downstream.

Audit log. Loghează fiecare apel cu cine, ce, când, ce input, ce output. Util pentru debugging, compliance, și pentru a îmbunătăți descrierile tool-urilor pe baza cazurilor unde modelul a ales prost.

Capcanele frecvente

Tool-uri prea generice. Un singur tool "query_database" cu SQL ca input e practic inutilizabil. Modelul nu știe schema, va greși. Mai bine 5 tool-uri specifice ("list_customers_by_region", "get_order_history") cu schemă clară.

Output prea voluminos. Dacă un tool returnează 5.000 de rânduri ca text, contextul Claude se umple și restul conversației se degradează. Limitează output-ul la ceea ce e util, oferă paginare, sau întoarce un sumar plus linkul către vizualizare completă în UI.

Eroarea ca string în loc de structurat. Returnează erori ca content cu flag isError: true. Modelul va înțelege că tool-ul a eșuat și va decide ce să facă mai departe (retry, întreabă utilizatorul, schimbă strategia).

Nu testezi tool-urile separat. Construiește teste unitare pentru fiecare handler de tool. Nu te baza pe Claude Desktop ca mediu de test. Tool-urile sunt cod, le testezi ca pe cod.

Numele tool-urilor inconsistente. Stabilește o convenție: verb_noun_qualifier de exemplu (list_customers, get_order_detail, create_invoice_draft). Modelul învață mai repede tipare consistente.

Cazuri reale în care MCP servers sunt răspunsul potrivit

La Ran·AI construim MCP servers ca strat de integrare standard pentru aplicații custom pe care clienții vor să le facă accesibile prin Claude. Câteva exemple de tipuri de cazuri unde abordarea funcționează:

• O aplicație internă cu UI complex pe care utilizatorii de business o folosesc rar și se pierd în meniuri. Un MCP server expune acțiunile principale, iar Claude Desktop devine un alt UI pentru aceleași operații.
• Un sistem legacy fără API public pentru care echipa tehnică nu vrea să expună acces direct. MCP server face wrapping, controlează permisiunile, logează tot.
• Procese cross-system unde un agent ar avea nevoie de mai multe surse (CRM + sistem facturare + ticketing). Un MCP server per sursă, plus un agent coordonator. Schimbi un sistem? Înlocuiești doar acel server.
• Memorie corporate cu Obsidian, expusă prin MCP. Echipele lucrează în Obsidian local, iar Claude poate citi documentația și politicile prin server.

Următorii pași

1. Alege un singur sistem intern. Cel cu cel mai mare ROI per oră de dezvoltare. De obicei: sistemul cel mai folosit de oameni de business non-tehnici.
2. Identifică 3 până la 5 operații pe care le-ar face acolo zi de zi.
3. Scrie un MCP server cu acele tool-uri. SDK-ul TypeScript sau Python, stdio transport. O zi de muncă pentru un MVP.
4. Conectează la Claude Desktop și testează cu 2 utilizatori reali. Observă unde modelul alege greșit tool-ul (înseamnă că descrierile sunt vagi) sau unde se blochează (înseamnă că un tool lipsește).
5. Iterează pe descrieri și schema. După 1-2 zile de feedback, ai un server care e util.
6. Mutați pe HTTP transport când e timpul să-l facem accesibil pentru toată echipa, cu autentificare per utilizator.

Dacă vrei o discuție despre construirea de MCP servers pentru un sistem concret, scrie-ne la contact@ranresults.com. Răspundem cu o opinie cinstită despre fezabilitate și parcursul recomandat.