Salt la conținutul principal
Română— Alege o limbă
Meniu

Serverul MCP: Instrumente, rezultate și implementare

Lecția 5 din 14 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Serverul, identitatea și instrucțiunile sale
  2. Un instrument per acțiune
  3. Rezultate utile fără interfață
  4. Adnotări și elicitare
  5. Conturi multiple și cunoștințe despre companie
  6. Implementarea endpoint-ului
  7. Evoluție fără întreruperi
  8. Mementouri de securitate
  9. Puncte cheie

Lecție rescrisă la 3 noiembrie 2026 pe baza paginii Build an MCP server din documentația OpenAI Plugins și a codului MCP TypeScript SDK (1.32.2). Lecția anterioară descria „acțiuni“ (defineAction, ActionError) dintr-un SDK inexistent; acest rol revine acum instrumentelor MCP. Surse: Build an MCP server · MCP TypeScript SDK.

Serverul, identitatea și instrucțiunile sale

Creați un server MCP cu un nume și o versiune stabile. În timpul inițializării, acesta poate returna și un câmp instructions pe care ChatGPT și Codex îl citesc alături de metadatele instrumentelor. Rezervați acest câmp pentru linii directoare care se aplică tuturor instrumentelor—cum ar fi o ordine obligatorie de apelare sau o limită de rată partajată—și mențineți conținutul principal în primele 512 de caractere. Nu copiați descrierile instrumentelor aici și nu încercați să schimbați personalitatea modelului.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

const server = new McpServer(
  { name: "acme-projects", version: "1.0.0" },
  {
    instructions:
      "Before modifying a project, call get_project to confirm its ID and status.",
  }
);

Un instrument per acțiune

Creați câte un instrument pentru fiecare acțiune distinctă: list_projects, get_project, update_project, în loc de un singur instrument universal cu numeroase moduri. Fiecare instrument combină un nume orientat spre acțiune, un titlu lizibil, o descriere care explică când să fie utilizat, o schemă de intrare explicită, o schemă de ieșire dacă returnează date structurate, adnotări precise și un handler care autorizează cererea înainte de a acționa. Modelul se bazează pe aceste metadate pentru a decide dacă și cum să apeleze instrumentul—tratați-l ca pe o parte a experienței utilizatorului.

import { z } from "zod";

const project = z.object({ id: z.string(), name: z.string(), status: z.enum(["active", "archived"]) });

server.registerTool(
  "get_project",
  {
    title: "View a project",
    description:
      "Use when the user wants details about a specific project in their Acme workspace. " +
      "Requires the ID returned by list_projects.",
    inputSchema: { id: z.string().min(1) },
    outputSchema: { project: project },
    annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
  },
  async ({ id }, extra) => {
    const user = await authenticate(extra); // Your access control (Lesson 8)
    const found = await loadProject(user, id); // Your data access
    if (!found) {
      return {
        isError: true,
        content: [{ type: "text", text: `No project ${id} is accessible with this account.` }],
      };
    }
    return {
      structuredContent: { project: found },
      content: [{ type: "text", text: `Project "${found.name}" (${found.status}).` }],
    };
  }
);

authenticate și loadProject sunt funcțiile dumneavoastră proprii. Punctul critic este plasarea lor: autorizarea are loc pe server, la fiecare cerere. Nu vă bazați niciodată pe model pentru a decide dacă un utilizator are permisiunea de a accesa date.

Rezultate utile fără interfață

Un rezultat al unui instrument poate conține trei elemente:

  • structuredContent: date concise pe care modelul le poate inspecta și reutiliza în apelurile ulterioare;
  • content: text sau alt conținut MCP care îl ajută să răspundă;
  • _meta: date destinate clientului, ascunse de model.

Returnați suficiente informații pentru ca modelul să finalizeze sarcina fără o componentă vizuală, folosind ID-uri stabile pe care instrumentele ulterioare le pot reutiliza. Două comportamente ale SDK-ului merită menționate. Un instrument care declară un outputSchema trebuie să returneze structuredContent conform în toate rezultatele reușite; în caz contrar, SDK va arunca o eroare de validare. O eroare de business—cum ar fi un proiect lipsă sau o acțiune refuzată—este semnalată printr-un rezultat cu isError: true însoțit de un text explicativ pe care modelul îl poate transmite utilizatorului; acest tip de rezultat ocolește validarea schemei de ieșire.

Nu includeți niciodată secrete, token-uri de acces sau date personale inutile într-un rezultat și nu tratați _meta ca pe un loc sigur de ascundere: acest câmp este ascuns de model, dar nu este protejat.

Adnotări și elicitare

Adnotările trebuie să reflecte comportamentul real al instrumentului: setați readOnlyHint la true doar dacă nu poate modifica nimic, destructiveHint la true dacă poate provoca un efect ireversibil sau greu de anulat și openWorldHint la true dacă atinge internetul public sau entități externe deschise. Acestea ajută ChatGPT și Codex să aleagă comportamentul corect de confirmare; ele nu înlocuiesc logica de autorizare, validare sau confirmare de pe serverul dumneavoastră.

Când serverul are nevoie de informații structurate lipsă din apel—cum ar fi o dată sau o alegere între două opțiuni—le poate solicita prin elicitare, un mecanism al protocolului MCP. Limitați acest lucru la ceea ce utilizatorul poate furniza în mod rezonabil; nu-l folosiți niciodată pentru a colecta secrete sau pentru a ocoli autentificarea normală.

Conturi multiple și cunoștințe despre companie

Două compatibilități opționale îmbunătățesc integrarea. Pentru a ajuta utilizatorii care conectează multiple conturi, expuneți un instrument de profil care este autentificat, read-only și marcat _meta["openai/profile"]: true. OpenAI folosește acest lucru pentru a identifica conturile conectate și pentru a ajuta utilizatorii să facă distincția între ele. Profilul este derivat din credențialele validate ale cererii, iar fiecare apel rămâne limitat la acele credențiale.

Funcționalitatea company knowledge din ChatGPT poate utiliza instrumentele read-only ale serverului dumneavoastră. Pentru a face un plugin eligibil ca sursă, implementați schemele de intrare standard pentru instrumentele search și fetch, marcați celelalte instrumente read-only cu readOnlyHint: true și returnați URL-uri absolute, deschise de utilizator, pentru sursele pe care modelul trebuie să le citeze.

Implementarea endpoint-ului

Depunerea publică necesită un server la o adresă HTTPS stabilă și accesibilă public. Acest endpoint trebuie să suporte transportul streamable HTTP, să răspundă la un URL stabil (de obicei terminând în /mcp), să îndeplinească cerințele de latență și disponibilitate ale fluxurilor dumneavoastră de lucru, să ajungă la serviciile și datele dumneavoastră, să păstreze limitele de autentificare și autorizare și să producă jurnale și metrici pentru inițializare și eșecurile apelurilor de instrumente.

Secure MCP Tunnel de la OpenAI vă permite să conectați un server privat la ChatGPT, dar nu îndeplinește cerințele pentru depunerea publică, la fel cum nu o face nici un tunel temporar sau o adresă locală. Dacă serverul trebuie să rămână privat, plasați un proxy HTTPS public în fața sa: mTLS gestionat de OpenAI autentifică ChatGPT ca client, OAuth 2.1 autentifică utilizatorii dumneavoastră, iar o listă de允许are IP—inclusiv intervalele publicate de OpenAI pentru conectorii ChatGPT, actualizate automat—poate fi adăugată, dar nu înlocuiește niciodată autentificarea.

Înainte de a intra în producție: injectați credențialele prin managerul de secrete al gazdei dumneavoastră, configurați serverul de autorizare și redirecționările, setați timeout-uri și limite de rată pentru instrumentele costisitoare sau vizibile extern, eliminați răspunsurile de depanare și datele personale inutile și verificați dacă jurnalele nu conțin token-uri sau rezultate sensibile. După implementare, repetați testele cu MCP Inspector împotriva adresei de producție.

Evoluție fără întreruperi

Mențineți numele și schemele instrumentelor publicate compatibile cu versiunile anterioare: adăugați câmpuri sau instrumente, dar nu rupeți contractele existente. Dacă metadatele se schimbă, reîmprospătați conexiunea și reluați suita de evaluare înainte de depunere. Pentru o interfață, schimbați ID-ul resursei când HTML, JavaScript sau CSS evoluează într-un mod care ar putea strica o componentă stocată în cache.

Mementouri de securitate

  • Toate intrările instrumentelor sunt neîncrezătoare: validați-le și impuneți autorizarea pe server
  • Cereți confirmare pentru scrierile cu impact ridicat
  • Păstrați secretele și datele sensibile în afara metadatelor și rezultatelor
  • Înregistrați suficient pentru a investiga, dar excludeți credențialele și datele personale inutile
  • Limitați rata pentru acțiunile costisitoare sau vizibile extern

Puncte cheie

  • Un server numit și versionat, cu instructions scurte și transversale
  • Un instrument per acțiune, cu titlu, descriere a intenției, scheme, adnotări și autorizare în handler
  • structuredContent conform cu schema de ieșire, isError: true pentru erorile de business, nimic secret în _meta
  • Publicare: HTTPS stabil și public prin streamable HTTP; Secure MCP Tunnel este insuficient
  • Contracte compatibile cu versiunile anterioare și ID-uri de resurse versionate