Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Strežnik MCP: orodja, rezultati in uvedba

Lekcija 5 od 14 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Strežnik, njegova identiteta in navodila
  2. Eno orodje na akcijo
  3. Uporabni rezultati brez vmesnika
  4. Anotacije in izsiljevanje informacij (elicitation)
  5. Več računov in znanje podjetja
  6. Uvedba končne točke
  7. Razvoj brez prekinitev
  8. Opomniki o varnosti
  9. Ključne ugotovitve

Lekcija je bila ponovno napisana 3. novembra 2026 na podlagi strani Build an MCP server iz dokumentacije za vtičnike OpenAI in kode MCP TypeScript SDK (različica 1.32.2). Prejšnja lekcija je opisovala “akcije” (defineAction, ActionError) iz neobstoječega SDK-ja; to vlogo zdaj prevzemajo orodja MCP. Viri: Build an MCP server · MCP TypeScript SDK.

Strežnik, njegova identiteta in navodila

Ustvari strežnik MCP s stabilnim imenom in različico. Med inicializacijo lahko vrne tudi polje instructions, ki ga ChatGPT in Codex prebereta skupaj z metapodatki orodij. To polje rezerviraj za smernice, ki veljajo za vsa orodja – kot je obvezen vrstni red klicev ali skupna omejitev hitrosti – in jedrnato vsebino ohrani v prvih 512 znakih. Sem ne kopiraj opisov orodij in ne poskušaj spremeniti osebnosti modela.

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

Eno orodje na akcijo

Za vsako ločeno akcijo ustvari posebno orodje: list_projects, get_project, update_project, namesto enega samega univerzalnega orodja z numerous načini. Vsako orodje združuje ime, usmerjeno v akcijo, berljiv naslov, opis, ki pojasnjuje, kdaj ga uporabiti, eksplicitno shemo vhoda, shemo izhoda (če vrača strukturirane podatke), natančne anotacije in rokodelnik (handler), ki pred izvedbo avtorizira zahtevo. Model se pri odločanju, ali in kako poklicati orodje, zanaša na te metapodatke – obravnavaj jih kot del uporabniške izkušnje.

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 in loadProject sta tvoji lastni funkciji. Ključna je njuna postavitev: avtorizacija poteka na strežniku, pri vsaki zahtevi. Nikoli se ne zanašaj na model, da bi se odločil, ali ima uporabnik dovoljenje za dostop do podatkov.

Uporabni rezultati brez vmesnika

Rezultat orodja lahko vsebuje tri stvari:

  • structuredContent: jedrnati podatki, ki jih model lahko pregleda in ponovno uporabi v naslednjih klicih;
  • content: besedilo ali druga vsebina MCP, ki mu pomaga pri odgovoru;
  • _meta: podatki, namenjeni odjemalcu, skriti modelu.

Vrni dovolj informacij, da lahko model dokonča nalogo brez vizualne komponente, z uporabo stabilnih ID-jev, ki jih lahko ponovno uporabijo naslednja orodja. Omeniti velja dva vidika delovanja SDK-ja. Orodje, ki deklarira outputSchema, mora v vseh uspešnih rezultatih vrniti skladno vsebino structuredContent; v nasprotnem primeru SDK vrže napako pri preverjanju veljavnosti. Poslovna napaka – kot je manjkajoč projekt ali zavrnjena akcija – se signalizira z rezultatom, ki ima isError: true, skupaj z razlagalnim besedilom, ki ga model lahko posreduje uporabniku; ta vrsta rezultata obide preverjanje sheme izhoda.

Nikoli ne vključuj skrivnosti, žetonov za dostop ali nepotrebnih osebnih podatkov v rezultat in ne obravnavaj _meta kot varnega skrivališča: to polje je modelu sicer skrito, vendar ni zaščiteno.

Anotacije in izsiljevanje informacij (elicitation)

Anotacije morajo odražati dejansko obnašanje orodja: readOnlyHint nastavi na true le, če orodje ne more ničesar spremeniti, destructiveHint na true, če lahko povzroči nepovraten ali težko razveljavljiv učinek, in openWorldHint na true, če se dotika javnega interneta ali odprtih zunanjih entitet. Pomagajo ChatGPT in Codex izbrati ustrezno obnašanje pri potrditvi; ne nadomeščajo pa logike avtorizacije, validacije ali potrditve na tvojem strežniku.

Ko strežnik potrebuje strukturirane informacije, ki manjkajo v klicu – kot je datum ali izbira med dvema možnostma – jih lahko zahteva prek mehanizma protokola MCP, imenovanega elicitation. To omeji na tisto, kar lahko uporabnik razumno zagotovi; nikoli ga ne uporabi za zbiranje skrivnosti ali obhod običajne avtentikacije.

Več računov in znanje podjetja

Dve opcijski združljivosti izboljšata integracijo. Da bi pomagal uporabnikom, ki povezujejo več računov, izpostavi orodje za profil, ki je avtenticirano, samo za branje in označeno z _meta["openai/profile"]: true. OpenAI to uporablja za identifikacijo povezanih računov in pomoč uporabnikom pri razlikovanju med njimi. Profil izhaja iz preverjenih poverilnic zahteve, vsak klic pa ostane omejen na te poverilnice.

Funkcija company knowledge v ChatGPT lahko uporablja tvoja strežniška orodja samo za branje. Da bi bil vtičnik upravičen kot vir, implementiraj standardne sheme vhoda za orodji search in fetch, druga orodja samo za branje označi z readOnlyHint: true in vrni absolutne URL-je, ki jih lahko uporabnik odpre, za vire, ki jih mora model navesti.

Uvedba končne točke

Javna objava zahteva strežnik na stabilnem, javno dosegljivem naslovu HTTPS. Ta končna točka mora podpirati prenos streamable HTTP, odgovarjati na stabilnem URL-ju (običajno se konča z /mcp), izpolnjevati zahteve glede zakasnitve in razpoložljivosti tvojih delovnih tokov, doseči tvoje storitve in podatke, ohranjati meje avtentikacije in avtorizacije ter proizvajati dnevnike in metrike za napake pri inicializaciji in klicih orodij.

Secure MCP Tunnel podjetja OpenAI ti omogoča povezavo zasebnega strežnika s ChatGPT, vendar ne izpolnjuje zahtev za javno objavo, prav tako ne začasni tunel ali lokalni naslov. Če mora strežnik ostati zaseben, predenj postavi javni posredniški strežnik HTTPS: mTLS, ki ga upravlja OpenAI, avtenticira ChatGPT kot odjemalca, OAuth 2.1 avtenticira tvoje uporabnike, dodatek seznama dovoljenih naslovov IP – vključno z obsegi, ki jih OpenAI objavlja za konektorje ChatGPT in se samodejno posodabljajo – je možen, vendar nikoli ne nadomešča avtentikacije.

Pred zagonom v živo: vnesi poverilnice prek upravitelja skrivnosti tvojega gostitelja, konfiguriraj strežnik za avtorizacijo in preusmeritve, nastavi časovne omejitve in omejitve hitrosti za draga ali navzven vidna orodja, odstrani odgovore za razhroščevanje in nepotrebne osebne podatke ter preveri, da dnevniki ne vsebujejo žetonov ali občutljivih rezultatov. Po uvedbi ponovno zaženi MCP Inspector proti produkcijskemu naslovu.

Razvoj brez prekinitev

Objavljena imena orodij in sheme ohrani združljive nazaj: dodajaj polja ali orodja, vendar ne krši obstoječih pogodb. Če se metapodatki spremenijo, osveži povezavo in pred objavo ponovno zaženi svoj evalvacijski niz. Za vmesnik spremeni ID vira, ko se HTML, JavaScript ali CSS spremenita tako, da bi lahko prekinila predpomnjeno komponento.

Opomniki o varnosti

  • Vsi vhodi orodij so nezaupljivi: validiraj jih in uveljavi avtorizacijo na strežniku
  • Zahtevaj potrditev za zapisovanja z velikim vplivom
  • Skrivnosti in občutljive podatke ohrani zunaj metapodatkov in rezultatov
  • Beleži dovolj za preiskavo, vendar izključi poverilnice in nepotrebne osebne podatke
  • Omeji hitrost dragih ali navzven vidnih akcij

Ključne ugotovitve

  • Imenovan in različičen strežnik s kratkimi, prečnimi instructions
  • Eno orodje na akcijo z naslovom, opisom namena, shemami, anotacijami in avtorizacijo v rokodelniku
  • structuredContent skladen s shemo izhoda, isError: true za poslovne napake, nič skrivnostnega v _meta
  • Objava: stabilen, javen HTTPS prek streamable HTTP; Secure MCP Tunnel ni zadosten
  • Pogodbe, združljive nazaj, in različičeni ID-ji virov