MCP (Model Context Protocol): Ghidul Complet pentru Dezvoltatori

Model Context Protocol (MCP) este un standard deschis creat de Anthropic care definește cum modelele AI comunică cu instrumente externe, surse de date și servicii. Gândește-te la el ca la "USB-C-ul AI-ului" - un conector universal care permite oricărui agent AI să comunice cu orice instrument printr-o interfață standardizată.

De la lansare, MCP a depășit 97 de milioane de descărcări lunare ale SDK-ului și a fost adoptat de toți furnizorii majori de AI: Anthropic, OpenAI, Google, Microsoft și Amazon. În acest ghid, vom explora tot ce trebuie să știi pentru a construi cu MCP.

De Ce Există MCP

Înainte de MCP, fiecare aplicație AI trebuia să construiască integrări personalizate pentru fiecare instrument pe care dorea să îl folosească. Vrei ca AI-ul tău să citească fișiere? Scrie cod personalizat. Să interogheze o bază de date? Mai mult cod personalizat. Să posteze pe Slack? Încă o integrare.

Aceasta a creat o problemă N×M: N aplicații AI, fiecare necesitând M integrări personalizate, ducând la efort duplicat și ecosisteme fragmentate.

MCP rezolvă asta cu un singur protocol pe care orice client AI îl poate folosi pentru a comunica cu orice server MCP:

Concepte Fundamentale

MCP are trei primitive fundamentale:

1. Instrumente (Tools)

Instrumentele sunt funcții pe care AI-ul le poate apela. Ele reprezintă acțiuni precum "creează un fișier", "interoghează o bază de date" sau "trimite un mesaj". Fiecare instrument are un nume, o descriere și un JSON Schema pentru parametrii săi.

{
  name: "create_issue",
  description: "Create a new GitHub issue",
  inputSchema: {
    type: "object",
    properties: {
      title: { type: "string", description: "Issue title" },
      body: { type: "string", description: "Issue body" },
      repo: { type: "string", description: "Repository name" }
    },
    required: ["title", "repo"]
  }
}

2. Resurse (Resources)

Resursele sunt date pe care AI-ul le poate citi. Ele reprezintă fișiere, înregistrări din baze de date, răspunsuri API sau orice altă sursă de date. Resursele sunt identificate prin URI-uri.

{
  uri: "file:///Users/dev/project/README.md",
  name: "Project README",
  mimeType: "text/markdown"
}

3. Prompts

Prompt-urile sunt șabloane reutilizabile care ajută la structurarea interacțiunilor. Pot include parametri dinamici și sunt utile pentru standardizarea fluxurilor de lucru comune.

{
  name: "code_review",
  description: "Review code changes for quality and security",
  arguments: [
    { name: "diff", description: "The code diff to review", required: true }
  ]
}

Arhitectură

MCP urmează o arhitectură client-server:

• Gazdă: Aplicația AI (Claude Desktop, Cursor, aplicația ta personalizată)
• Client: Menține o conexiune 1:1 cu un server MCP
• Server: Expune instrumente, resurse și prompts clientului
• Transport: Comunicarea se face prin JSON-RPC 2.0 peste stdio (local) sau Server-Sent Events (remote)

Construirea unui Server MCP

Hai să construim un server MCP practic care interacționează cu o listă de sarcini stocată într-un fișier JSON.

Configurare

mkdir mcp-todo-server && cd mcp-todo-server
npm init -y
npm install @modelcontextprotocol/sdk zod

Implementarea Serverului

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

const TODO_FILE = "./todos.json";

function readTodos(): { id: number; text: string; done: boolean }[] {
  if (!fs.existsSync(TODO_FILE)) return [];
  return JSON.parse(fs.readFileSync(TODO_FILE, "utf-8"));
}

function writeTodos(todos: { id: number; text: string; done: boolean }[]) {
  fs.writeFileSync(TODO_FILE, JSON.stringify(todos, null, 2));
}

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

// Tool: Add a todo
server.tool(
  "add_todo",
  "Add a new todo item",
  { text: z.string().describe("The todo text") },
  async ({ text }) => {
    const todos = readTodos();
    const newTodo = { id: Date.now(), text, done: false };
    todos.push(newTodo);
    writeTodos(todos);
    return { content: [{ type: "text", text: `Added: "${text}"` }] };
  }
);

// Tool: List todos
server.tool(
  "list_todos",
  "List all todo items",
  {},
  async () => {
    const todos = readTodos();
    const list = todos
      .map((t) => `${t.done ? "✅" : "⬜"} [${t.id}] ${t.text}`)
      .join("\n");
    return { content: [{ type: "text", text: list || "No todos yet." }] };
  }
);

// Tool: Complete a todo
server.tool(
  "complete_todo",
  "Mark a todo as completed",
  { id: z.number().describe("The todo ID to complete") },
  async ({ id }) => {
    const todos = readTodos();
    const todo = todos.find((t) => t.id === id);
    if (!todo) return { content: [{ type: "text", text: "Todo not found." }] };
    todo.done = true;
    writeTodos(todos);
    return { content: [{ type: "text", text: `Completed: "${todo.text}"` }] };
  }
);

// Resource: Current todos as a readable resource
server.resource(
  "todos://list",
  "Current todo list",
  async () => ({
    contents: [{
      uri: "todos://list",
      mimeType: "application/json",
      text: JSON.stringify(readTodos(), null, 2),
    }],
  })
);

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

Configurare

Pentru a folosi acest server cu Claude Desktop, adaugă-l în configurația ta:

{
  "mcpServers": {
    "todo": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcp-todo-server/src/index.ts"]
    }
  }
}

Construirea unui Client MCP

Poți construi și un client personalizat care se conectează la orice server MCP:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["tsx", "./src/index.ts"],
});

const client = new Client({ name: "my-client", version: "1.0.0" });
await client.connect(transport);

// List available tools
const { tools } = await client.listTools();
console.log("Available tools:", tools.map((t) => t.name));

// Call a tool
const result = await client.callTool({
  name: "add_todo",
  arguments: { text: "Write MCP blog post" },
});
console.log(result);

Servere MCP Populare

Ecosistemul MCP a crescut rapid. Iată câteva dintre cele mai populare servere:

MCP vs A2A (Agent-to-Agent)

În timp ce MCP gestionează comunicarea agent-instrument, protocolul A2A (Agent-to-Agent) al Google gestionează comunicarea agent-agent. Sunt complementare:

• MCP: Cum un agent AI folosește instrumente (integrare verticală)
• A2A: Cum agenții AI colaborează între ei (integrare orizontală)

Cele Mai Bune Practici

1. Menține serverele focalizate: Un server per domeniu (server GitHub, server Slack, etc.). Nu construi servere monolitice.
2. Validează intrările cu Zod: Validează întotdeauna intrările instrumentelor cu scheme adecvate.
3. Gestionează erorile cu grație: Returnează mesaje de eroare semnificative, nu stack traces.
4. Folosește resurse pentru date doar-citire: Dacă AI-ul trebuie doar să citească date, expune-le ca resursă în loc de instrument.
5. Adaugă descrieri adecvate: Descrierile bune ale instrumentelor și parametrilor ajută AI-ul să înțeleagă când și cum să folosească fiecare instrument.
6. Testează cu MCP Inspector: Folosește npx @modelcontextprotocol/inspector pentru a testa serverul interactiv.

Începe

# Create a new MCP server from template
npx @modelcontextprotocol/create-server my-server

# Test with the MCP Inspector
npx @modelcontextprotocol/inspector npx tsx ./src/index.ts

Concluzie

MCP a devenit standardul de facto pentru utilizarea instrumentelor AI în 2026. Indiferent dacă construiești agenți AI personalizați, extinzi Claude Code sau creezi integrări pentru platforme existente, înțelegerea MCP este esențială. Protocolul este suficient de simplu pentru a fi învățat într-o după-amiază, dar suficient de puternic pentru a construi fluxuri de lucru AI de nivel producție.

Pașii următori:

• Explorează Specificația MCP
• Răsfoiește serverele MCP existente pentru inspirație
• Construiește primul tău server cu SDK-ul TypeScript sau Python
• Testează-l cu Claude Desktop sau MCP Inspector