Server MCP: nástroje, výsledky a nasazení
Na této stránce
Lekce přepsána 3. listopadu 2026 na základě stránky Build an MCP server z dokumentace OpenAI Plugins a kódu MCP TypeScript SDK (1.32.2). Předchozí lekce popisovala „akce“ (
defineAction,ActionError) z neexistujícího SDK; tuto roli nyní přebírají nástroje MCP. Zdroje: Build an MCP server · MCP TypeScript SDK.
Server, jeho identita a pokyny
Vytvoř server MCP se stabilním názvem a verzí. Během inicializace může server vrátit také pole instructions, které si ChatGPT a Codex přečtou společně s metadaty nástrojů. Vyhraď toto pole pro pokyny platné pro všechny nástroje – například povinné pořadí volání nebo společný limit rychlosti – a udržuj hlavní obsah v rámci prvních 512 znaků. Nezkopírovávej sem popisy nástrojů a nepokusívej se měnit osobnost 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 pro jednu akci
Vytvoř jeden nástroj pro každou samostatnou akci: list_projects, get_project, update_project, místo jediného univerzálního nástroje s mnoha režimy. Každý nástroj kombinuje název orientovaný na akci, čitelný titulek, popis vysvětlující, kdy jej použít, explicitní schéma vstupu, schéma výstupu (pokud vrací strukturovaná data), přesné anotace a obslužnou rutinu (handler), která požadavek před provedením autorizuje. Model se spoléhá na tato metadata při rozhodování, zda a jak nástroj zavolat – zacházej s nimi jako se součástí uživatelské zkušenosti.
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}).` }],
};
}
);
Funkce authenticate a loadProject jsou tvoje vlastní. Klíčový je jejich umístění: autorizace probíhá na serveru u každého požadavku. Nikdy se nespoléhej na to, že model rozhodne, zda má uživatel oprávnění přistupovat k datům.
Užitečné výsledky bez rozhraní
Výsledek nástroje může obsahovat tři věci:
structuredContent: stručná data, která si model může prohlédnout a znovu použít v následných voláních;content: text nebo jiný obsah MCP, který mu pomůže odpovědět;_meta: data určená pro klienta, skrytá před modelem.
Vrať dostatek informací, aby model mohl úkol dokončit bez vizuální komponenty, a používej stabilní ID, která mohou znovu využít následné nástroje. Stojí za zmínku dvě chování SDK. Nástroj deklarující outputSchema musí ve všech úspěšných výsledcích vracet vyhovující structuredContent; jinak SDK vyhodí chybu validace. Obchodní chyba – například chybějící projekt nebo zamítnutá akce – se signalizuje výsledkem s isError: true doprovázeným vysvětlujícím textem, který model předá uživateli; tento typ výsledku obchází validaci výstupního schématu.
Nikdy do výsledku nezahrnuj tajné klíče, přístupové tokeny ani zbytečná osobní data a nepovažuj _meta za bezpečné útočiště: toto pole je sice před modelem skryté, ale není chráněné.
Anotace a elicitation (vyžádání informací)
Anotace musí odpovídat skutečnému chování nástroje: nastav readOnlyHint na true pouze tehdy, pokud nástroj nic nemění, destructiveHint na true, pokud může způsobit nevratný nebo těžko vratný účinek, a openWorldHint na true, pokud zasahuje do veřejného internetu nebo otevřených externích entit. Pomáhají ChatGPT a Codex vybrat správné chování při potvrzování; nenahrazují však logiku autorizace, validace ani potvrzení na tvém serveru.
Když server potřebuje strukturované informace, které v požadavku chybí – například datum nebo výběr mezi dvěma možnostmi – může je vyžádat prostřednictvím elicitation, což je mechanismus protokolu MCP. Omez to pouze na to, co může uživatel rozumně poskytnout; nikdy to nepoužívej ke sběru tajných údajů nebo k obcházení běžné autentizace.
Vícero účtů a firemní znalosti
Dvě volitelné kompatibility zlepšují integraci. Abychom pomohli uživatelům připojujícím více účtů, exposeuj profilový nástroj, který je autentizovaný, pouze pro čtení a označený _meta["openai/profile"]: true. OpenAI to používá k identifikaci připojených účtů a pomáhá uživatelům rozlišovat mezi nimi. Profil je odvozen z ověřených pověření požadavku a každé volání zůstává omezeno pouze na tato pověření.
Funkce company knowledge (firemní znalosti) v ChatGPT může využívat nástroje tvého serveru určené pouze pro čtení. Aby byl plugin způsobilý jako zdroj, implementuj standardní vstupní schémata pro nástroje search a fetch, označ ostatní nástroje pouze pro čtení pomocí readOnlyHint: true a vracej absolutní URL adresy, které může uživatel otevřít, pro zdroje, které musí model citovat.
Nasazení koncového bodu
Veřejné odeslání vyžaduje server na stabilní, veřejně dostupné adrese HTTPS. Tento koncový bod musí podporovat transport streamable HTTP, odpovídat na stabilní URL (obvykle končící na /mcp), splňovat požadavky na latenci a dostupnost tvých pracovních postupů, dosáhnout na tvé služby a data, zachovat hranice autentizace a autorizace a produkovat logy a metriky pro selhání inicializace a volání nástrojů.
Secure MCP Tunnel od OpenAI ti umožňuje připojit soukromý server k ChatGPT, ale nesplňuje požadavky pro veřejné odeslání, stejně jako dočasný tunel nebo lokální adresa. Pokud musí server zůstat soukromý, umísti před něj veřejnou HTTPS proxy: mTLS spravované OpenAI autentizuje ChatGPT jako klienta, OAuth 2.1 autentizuje tvé uživatele a lze přidat seznam povolených IP adres – včetně rozsahů publikovaných OpenAI pro konektory ChatGPT, které se automaticky aktualizují – ale nikdy nenahrazuje autentizaci.
Než přejdeš do ostrého provozu: injektuj pověření prostřednictvím správce tajných klíčů svého hostitele, nakonfiguruj autorizační server a přesměrování, nastav časové limity a omezení rychlosti pro náročné nebo externě viditelné nástroje, odstraň ladící odpovědi a zbytečná osobní data a ověř, že logy neobsahují tokeny ani citlivé výsledky. Po nasazení přehraj MCP Inspector proti produkční adrese.
Vývoj bez narušení funkčnosti
Udržuj publikované názvy nástrojů a schémata zpětně kompatibilní: přidávej pole nebo nástroje, ale nerozbíjej existující kontrakty. Pokud se změní metadata, obnov připojení a před odesláním přehrej svou hodnoticí sadu. U rozhraní změň ID zdroje, když se HTML, JavaScript nebo CSS vyvíjejí způsobem, který by mohl rozbít komponentu v mezipaměti.
Připomenutí bezpečnosti
- Všechny vstupy nástrojů jsou nedůvěryhodné: validuj je a vynucuj autorizaci na serveru
- Vyžaduj potvrzení pro zápisy s vysokým dopadem
- Udržuj tajné klíče a citlivá data mimo metadata a výsledky
- Loguj dostatečně pro vyšetřování, ale vylučuj pověření a zbytečná osobní data
- Omezuj rychlost pro náročné nebo externě viditelné akce
Klíčové poznatky
- Pojmenovaný a verzovaný server s krátkými, průřezovými
instructions - Jeden nástroj na akci s titulkem, popisem záměru, schématy, anotacemi a autorizací v handleru
structuredContentv souladu s výstupním schématem,isError: truepro obchodní chyby, žádná tajemství v_meta- Publikace: stabilní, veřejné HTTPS přes streamable HTTP; Secure MCP Tunnel nestačí
- Zpětně kompatibilní kontrakty a verzovaná ID zdrojů