Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Server MCP: nástroje, výsledky a nasadenie

Lekcia 5 z 14 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Server, jeho identita a inštrukcie
  2. Jeden nástroj na jednu akciu
  3. Užitočné výsledky bez rozhrania
  4. Anotácie a elicitácia
  5. Viacero účtov a firemné znalosti
  6. Nasadenie koncového bodu
  7. Vývoj bez porušovania funkčnosti
  8. Pripomienky k bezpečnosti
  9. Kľúčové poznatky

Lekcia prepísaná 3. novembra 2026 na základe stránky Build an MCP server z dokumentácie OpenAI Plugins a kódu MCP TypeScript SDK (1.32.2). Predchádzajúca lekcia popisovala „akcie“ (defineAction, ActionError) z neexistujúceho SDK; túto úlohu teraz preberajú nástroje MCP. Zdroje: Build an MCP server · MCP TypeScript SDK.

Server, jeho identita a inštrukcie

Vytvor server MCP so stabilným názvom a verziou. Počas inicializácie môže vrátiť aj pole instructions, ktoré si ChatGPT a Codex prečítajú spolu s metadátami nástrojov. Vyhraď toto pole pre smernice platné pre všetky nástroje – ako je povinné poradie volaní alebo spoločný limit rýchlosti – a udržuj základný obsah v rámci prvých 512 znakov. Nekopíruj sem popisy nástrojov a nepokúšaj sa meniť osobnosť modelu.

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.",
  }
);

Jeden nástroj na jednu akciu

Vytvor jeden nástroj pre každú distinctnú akciu: list_projects, get_project, update_project, namiesto jedného univerzálneho nástroja s numerous režimami. Každý nástroj kombinuje názov orientovaný na akciu, čitateľný titulok, popis vysvetľujúci, kedy ho použiť, explicitnú schému vstupu, schému výstupu, ak vracia štruktúrované dáta, presné anotácie a handler, ktorý autorizuje požiadavku pred vykonaním akcie. Model sa spolieha na tieto metadáta pri rozhodovaní, či a ako nástroj zavolať – považuj to za súčasť používateľskej skúsenosti.

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}).` }],
    };
  }
);

Funkcie authenticate a loadProject sú tvoje vlastné. Kľúčový je ich spôsob umiestnenia: autorizácia prebieha na serveri pri každej požiadavke. Nikdy sa nespoliehaj na model pri rozhodovaní, či má používateľ povolenie pristupovať k dátam.

Užitočné výsledky bez rozhrania

Výsledok nástroja môže obsahovať tri veci:

  • structuredContent: stručné dáta, ktoré si model môže prezrieť a znovu použiť v následných volaniach;
  • content: text alebo iný obsah MCP, ktorý mu pomôže odpovedať;
  • _meta: dáta určené pre klienta, skryté pred modelom.

Vráť dostatok informácií, aby model dokončil úlohu bez vizuálnej zložky, pomocou stabilných ID, ktoré môžu následné nástroje znovu použiť. Dva spôsoby správania SDK stoja za zmienku. Nástroj deklarujúci outputSchema musí vo všetkých úspešných výsledkoch vrátiť vyhovujúce structuredContent; inak SDK vyhodí chybu validácie. Obchodná chyba – ako chýbajúci projekt alebo zamietnutá akcia – sa signalizuje výsledkom s isError: true sprevádzaným vysvetľujúcim textom, ktorý model môže postúpiť používateľovi; tento typ výsledku obchádza validáciu výstupnej schémy.

Nikdy nezahŕňaj tajné kľúče, prístupové tokeny ani nepotrebné osobné údaje do výsledku a nepovažuj _meta za bezpečné útočisko: toto pole je síce skryté pred modelom, ale nie je chránené.

Anotácie a elicitácia

Anotácie musia odrážať skutočné správanie nástroja: nastav readOnlyHint na true len ak nemôže nič meniť, destructiveHint na true ak môže spôsobiť nezvratný alebo ťažko vratný účinok a openWorldHint na true ak sa dotýka verejného internetu alebo otvorených externých entít. Pomáhajú ChatGPT a Codex vybrať správne správanie pri potvrdení; nenahrádzajú však logiku autorizácie, validácie ani potvrdenia na tvojom serveri.

Keď server potrebuje štruktúrované informácie chýbajúce vo volaní – ako dátum alebo výber medzi dvoma možnosťami – môže si ich vyžiadať prostredníctvom elicitácie, mechanizmu protokolu MCP. Obmedz to na to, čo môže používateľ rozumne poskytnúť; nikdy to nepoužívaj na zber tajomstiev alebo obchádzanie bežnej autentifikácie.

Viacero účtov a firemné znalosti

Dve voliteľné kompatibility zlepšujú integráciu. Aby si pomohol používateľom pripájajúcim viacero účtov, vystav nástroj profilu, ktorý je autentifikovaný, len na čítanie a označený _meta["openai/profile"]: true. OpenAI to používa na identifikáciu pripojených účtov a pomoc používateľom rozlíšiť ich medzi sebou. Profil je odvodený od validovaných poverení požiadavky a každé volanie zostáva obmedzené na tieto poverenia.

Funkcia company knowledge v ChatGPT môže využívať tvoje nástroje len na čítanie. Aby bol plugin spôsobilý ako zdroj, implementuj štandardné schémy vstupu pre nástroje search a fetch, označ ostatné nástroje len na čítanie pomocou readOnlyHint: true a vráť absolútne URL adresy otvárateľné používateľom pre zdroje, ktoré musí model citovať.

Nasadenie koncového bodu

Verejné odovzdanie vyžaduje server na stabilnej, verejne dostupnej HTTPS adrese. Tento koncový bod musí podporovať transport streamable HTTP, odpovedať na stabilnej URL (zvyčajne končiacej na /mcp), spĺňať požiadavky na latenciu a dostupnosť tvojich workflow, dosahovať tvoje služby a dáta, zachovávať hranice autentifikácie a autorizácie a produkovať logy a metriky pre zlyhania inicializácie a volaní nástrojov.

Secure MCP Tunnel od OpenAI ti umožňuje pripojiť súkromný server k ChatGPT, ale nespĺňa požiadavky na verejné odovzdanie, rovnako ako dočasný tunel alebo lokálna adresa. Ak musí server zostať súkromný, umiestni pred neho verejný HTTPS proxy: mTLS spravované OpenAI autentifikuje ChatGPT ako klienta, OAuth 2.1 autentifikuje tvojich používateľov a možno pridať zoznam povolených IP adries – vrátane rozsahov publikovaných OpenAI pre konektory ChatGPT, aktualizovaných automaticky – ale nikdy nenahrádza autentifikáciu.

Pred spustením: injektuj poverenia cez správcu tajomstiev svojho hostiteľa, nakonfiguruj autorizačný server a presmerovania, nastav časové limity a obmedzenia rýchlosti pre nákladné alebo externe viditeľné nástroje, odstráň ladiace odpovede a nepotrebné osobné údaje a over, že logy neobsahujú tokeny ani citlivé výsledky. Po nasadení replayni MCP Inspector proti produkčnej adrese.

Vývoj bez porušovania funkčnosti

Udržuj publikované názvy nástrojov a schémy spätne kompatibilné: pridávaj polia alebo nástroje, ale nerozbíjaj existujúce kontrakty. Ak sa menia metadáta, obnov pripojenie a replayni svoju hodnotiacu sadu pred odovzdaním. Pre rozhranie zmeň ID zdroja, keď sa HTML, JavaScript alebo CSS vyvinú spôsobom, ktorý by mohol rozbiť komponent v cache.

Pripomienky k bezpečnosti

  • Všetky vstupy nástrojov sú nedôveryhodné: validuj ich a presadzuj autorizáciu na serveri
  • Vyžaduj potvrdenie pre zápisy s vysokým dopadom
  • Udržuj tajomstvá a citlivé dáta mimo metadát a výsledkov
  • Loguj dostatok informácií na vyšetrovanie, ale vylúč poverenia a nepotrebné osobné údaje
  • Obmedz rýchlosť pre nákladné alebo externe viditeľné akcie

Kľúčové poznatky

  • Menovaný, verziovaný server s krátkymi, prierezovými instructions
  • Jeden nástroj na akciu s titulkom, popisom zámeru, schémami, anotáciami a autorizáciou v handleri
  • structuredContent v súlade s výstupnou schémou, isError: true pre obchodné chyby, nič tajné v _meta
  • Publikácia: stabilné, verejné HTTPS cez streamable HTTP; Secure MCP Tunnel nestačí
  • Spätne kompatibilné kontrakty a verziované ID zdrojov