Az MCP-kiszolgáló: eszközök, eredmények és üzembe helyezés
Ezen az oldalon
A leckét 2026. november 3-án írtuk át az OpenAI Plugins dokumentációjának Build an MCP server oldala és az MCP TypeScript SDK kódja (1.32.2) alapján. Az előző lecke egy nem létező SDK „műveleteit“ (
defineAction,ActionError) írta le; ezt a szerepet most az MCP-eszközök töltik be. Források: Build an MCP server · MCP TypeScript SDK.
A kiszolgáló, identitása és utasításai
Hozz létre egy MCP-kiszolgálót stabil névvel és verziószámmal. Inicializáláskor visszaadhat egy instructions mezőt is, amelyet a ChatGPT és a Codex az eszközmetaadatok mellett olvas be. Ezt a mezőt csak olyan, minden eszközre érvényes irányelvekhez tartsd fenn, mint a kötelező hívási sorrend vagy egy közös sebességkorlát, és a tartalmat tartsd az első 512 karakteren belül. Ne másold be ide az eszközleírásokat, és ne próbáld megváltoztatni a modell személyiségét.
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.",
}
);
Egy művelet, egy eszköz
Minden egyes elkülönült művelethezz hozz létre egy eszközt: list_projects, get_project, update_project, ne pedig egyetlen mindent lefedő eszközt számos móddal. Minden eszköz egyesít egy cselekvésorientált nevet, egy olvasható címet, egy leírást arról, hogy mikor használd, egy explicit bemeneti sémát, egy kimeneti sémát (ha strukturált adatot ad vissza), pontos annotációkat, és egy kezelőt, amely hitelesíti a kérést, mielőtt cselekedne. A modell erre a metaadatra támaszkodik, hogy eldöntse, hívja-e az eszközt, és hogyan – kezeld ezt a felhasználói élmény részének.
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}).` }],
};
}
);
Az authenticate és a loadProject a te saját függvényeid. A lényeg a helyük: a hitelesítés a kiszolgálón történik, minden egyes kéréskor. Soha ne bízd a modellre, hogy eldöntse, van-e jogosultsága a felhasználónak az adatok hozzáféréséhez.
Hasznos eredmények felület nélkül
Egy eszköz eredménye három dolgot hordozhat:
structuredContent: tömör adat, amelyet a modell megvizsgálhat és felhasználhat a későbbi hívásokban;content: szöveg vagy egyéb MCP-tartalom, amely segít a válaszadásban;_meta: a kliensnek szánt adat, amely rejtve marad a modell elől.
Adj vissza annyi információt, hogy a modell vizuális komponens nélkül is befejezhesse a feladatot, olyan stabil azonosítókat használva, amelyeket a későbbi eszközök újra felhasználhatnak. Két SDK-viselkedést érdemes megjegyezni. Egy outputSchema-t deklaráló eszköznek minden sikeres eredményben compliant structuredContent-et kell visszaadnia; ellenkező esetben az SDK validációs hibát dob. Egy üzleti hiba – például egy hiányzó projekt vagy egy megtagadott művelet – egy isError: true értékű eredménnyel jelezhető, magyarázó szöveggel kiegészítve, amelyet a modell továbbíthat a felhasználónak; ez a típusú eredmény megkerüli a kimeneti séma validálását.
Soha ne adj meg titkokat, hozzáférési tokeneket vagy felesleges személyes adatokat egy eredményben, és ne kezeld a _meta mezőt biztonságos búvóhelyként: ez a mező rejtve marad a modell elől, de nincs védve.
Annotációk és információkérés
Az annotációknak tükrözniük kell az eszköz tényleges viselkedését: a readOnlyHint csak akkor legyen true, ha semmit sem módosíthat, a destructiveHint akkor legyen true, ha visszafordíthatatlan vagy nehezen visszavonható hatást okozhat, az openWorldHint pedig akkor legyen true, ha a nyilvános internetet vagy nyílt külső entitásokat érinti. Ezek segítik a ChatGPT-t és a Codexet a megfelelő megerősítési viselkedés kiválasztásában; nem helyettesítik a hitelesítést, validálást vagy megerősítési logikát a kiszolgálódon.
Amikor a kiszolgálónak olyan strukturált információra van szüksége, amely hiányzik a hívásból – például egy dátumra vagy választásra két lehetőség között –, kérheti azt elicitation (információkérés) útján, ami az MCP-protokoll mechanizmusa. Korlátozd ezt arra, amit a felhasználó ésszerűen meg tud adni; soha ne használd titkok gyűjtésére vagy a normál hitelesítés megkerülésére.
Több fiók és vállalati tudás
Két opcionális kompatibilitás javítja az integrációt. A több fiókot összekötő felhasználók segítéséhez tegyél közzé egy profil eszközt, amely hitelesített, csak olvasható, és _meta["openai/profile"]: true jelöléssel van ellátva. Az OpenAI ezt használja a csatlakoztatott fiókok azonosítására és a felhasználók közötti megkülönböztetésre. A profil a kérés validált hitelesítő adataiból származik, és minden hívás ezekre a hitelesítő adatokra korlátozódik.
A ChatGPT vállalati tudás (company knowledge) funkciója használhatja a kiszolgálód csak olvasható eszközeit. Ahhoz, hogy egy bővítmény forrásként alkalmas legyen, implementáld a search és fetch eszközök szabványos bemeneti sémáit, jelöld meg a többi csak olvasható eszközt readOnlyHint: true értékkel, és adj vissza abszolút, felhasználó által megnyitható URL-címeket azokhoz a forrásokhoz, amelyeket a modellnek idéznie kell.
A végpont üzembe helyezése
A nyilvános beküldéshez egy stabil, nyilvánosan elérhető HTTPS-címen futó kiszolgáló szükséges. Ennek a végpontnak támogatnia kell a streamable HTTP transzportot, válaszolnia kell egy stabil URL-en (jellemzően /mcp végződéssel), meg kell felelnie a munkafolyamataid késleltetési és rendelkezésre állási követelményeinek, el kell érnie a szolgáltatásaidat és adataidat, meg kell őriznie a hitelesítési és engedélyezési határokat, valamint naplókat és metrikákat kell előállítania az inicializálási és eszköz hívási hibákhoz.
Az OpenAI Secure MCP Tunnel lehetősége lehetővé teszi egy privát kiszolgáló csatlakoztatását a ChatGPT-hez, de ez nem felel meg a nyilvános beküldés követelményeinek, ahogy egy ideiglenes alagút vagy helyi cím sem. Ha a kiszolgálónak privátnak kell maradnia, helyezz elé egy nyilvános HTTPS-proxyt: az OpenAI által kezelt mTLS hitelesíti a ChatGPT-t mint klienst, az OAuth 2.1 hitelesíti a felhasználóidat, és egy IP-engedélyezési lista – beleértve az OpenAI által a ChatGPT-csatlakozókhoz közzétett, automatikusan frissülő tartományokat – hozzáadható, de soha nem helyettesíti a hitelesítést.
Élesítés előtt: injektáld a hitelesítő adatokat a hosztod titokkezelőjén keresztül, konfiguráld a hitelesítő kiszolgálót és az átirányításokat, állíts be időtúllépéseket és sebességkorlátokat a költséges vagy külvilág felé látható eszközökhöz, távolítsd el a hibakeresési válaszokat és a felesleges személyes adatokat, valamint ellenőrizd, hogy a naplók nem tartalmaznak tokeneket vagy érzékeny eredményeket. Üzembe helyezés után játszd le az MCP Inspectort a produkciós címen.
Fejlődés törés nélkül
Tartsd meg a közzétett eszközneveket és sémákat visszafelé kompatibilisen: adj hozzá mezőket vagy eszközöket, de ne szegd meg a meglévő szerződéseket. Ha a metaadatok megváltoznak, frissítsd a kapcsolatot, és játszd le újra az értékelési csomagodat a beküldés előtt. Egy felület esetén változtasd meg az erőforrás-azonosítót, ha a HTML, JavaScript vagy CSS úgy evolveszik, hogy az egy gyorsítótárazott komponenst meghibásodást okozhat.
Biztonsági emlékeztetők
- Minden eszköz bemenet megbízhatatlan: validáld és érvényesítsd a jogosultságot a kiszolgálón
- Kérj megerősítést a nagy hatású írási műveletekhez
- Tartsd távol a titkokat és az érzékeny adatokat a metaadatoktól és az eredményektől
- Naplózz eléggé a kivizsgáláshoz, de zárj ki hitelesítő adatokat és felesleges személyes adatokat
- Korlátozd a sebességet a költséges vagy külvilág felé látható műveleteknél
Főbb megállapítások
- Névvel és verzióval ellátott kiszolgáló rövid, átfogó
instructionsutasításokkal - Egy műveletre egy eszköz, címmel, szándékleírással, sémákkal, annotációkkal és hitelesítéssel a kezelőben
- A kimeneti sémának megfelelő
structuredContent, üzleti hibákhozisError: true, semmi titkos a_metamezőben - Közzététel: stabil, nyilvános HTTPS a streamable HTTP keresztül; a Secure MCP Tunnel nem elegendő
- Visszafelé kompatibilis szerződések és verziókezelt erőforrás-azonosítók