MCP poslužitelj: alati, rezultati i implementacija
Na ovoj stranici
Lekcija je ponovno napisana 3. studenog 2026. na temelju stranice Build an MCP server iz dokumentacije OpenAI Plugins i koda MCP TypeScript SDK-a (verzija 1.32.2). Prethodna lekcija opisivala je “akcije” (
defineAction,ActionError) iz nepostojećeg SDK-a; tu ulogu sada preuzimaju MCP alati. Izvori: Build an MCP server · MCP TypeScript SDK.
Poslužitelj, njegov identitet i upute
Stvori MCP poslužitelj sa stabilnim imenom i verzijom. Tijekom inicijalizacije može vratiti i polje instructions koje ChatGPT i Codex čitaju uz metapodatke alata. Ovo polje rezerviraj za smjernice koje se primjenjuju na sve alate – poput obaveznog redoslijeda poziva ili zajedničkog ograničenja stope – i zadrži ključni sadržaj unutar prvih 512 znakova. Ovdje nemoj kopirati opise alata niti pokušavati mijenjati osobnost 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.",
}
);
Jedan alat po radnji
Stvori po jedan alat za svaku zasebnu radnju: list_projects, get_project, update_project, umjesto jednog univerzalnog alata s brojnim načinima rada. Svaki alat kombinira ime usmjereno na radnju, čitljiv naslov, opis koji objašnjava kada ga koristiti, eksplicitnu shemu ulaza, shemu izlaza ako vraća strukturirane podatke, precizne anotacije i rukovatelja (handler) koji autorizira zahtjev prije izvršenja radnje. Model se oslanja na ove metapodatke kako bi odlučio hoće li i kako pozvati alat – tretiraj ih kao dio korisničkog iskustva.
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}).` }],
};
}
);
Funkcije authenticate i loadProject su tvoje vlastite. Ključna je njihova pozicija: autorizacija se događa na poslužitelju, uz svaki zahtjev. Nikada se ne oslanjaj na model da odluči ima li korisnik dopuštenje za pristup podacima.
Korisni rezultati bez sučelja
Rezultat alata može sadržavati tri stvari:
structuredContent: sažeti podaci koje model može pregledati i ponovno upotrijebiti u narednim pozivima;content: tekst ili drugi MCP sadržaj koji mu pomaže u odgovoru;_meta: podaci namijenjeni klijentu, skriveni od modela.
Vrati dovoljno informacija da model može završiti posao bez vizualne komponente, koristeći stabilne ID-ove koje naknadni alati mogu ponovno upotrijebiti. Dva ponašanja SDK-a vrijedi istaknuti. Alat koji deklarira outputSchema mora vratiti usklađen structuredContent u svim uspješnim rezultatima; u suprotnom, SDK baca pogrešku validacije. Poslovna pogreška – poput nedostajućeg projekta ili odbijene radnje – signalizira se rezultatom s isError: true popraćenim objašnjavajućim tekstom koji model može proslijediti korisniku; ova vrsta rezultata zaobilazi validaciju sheme izlaza.
Nikada ne uključuj tajne, pristupne tokene ili nepotrebne osobne podatke u rezultat i nemoj tretirati _meta kao sigurno skrovište: ovo je polje skriveno od modela, ali nije zaštićeno.
Anotacije i elicitation (iznuđivanje podataka)
Anotacije moraju odražavati stvarno ponašanje alata: postavi readOnlyHint na true samo ako alat ne može ništa modificirati, destructiveHint na true ako može uzrokovati nepovratan ili teško poništiv učinak, a openWorldHint na true ako dotiče javni internet ili otvorene vanjske entitete. One pomažu ChatGPT-u i Codexu odabrati ispravno ponašanje potvrde; ne zamjenjuju logiku autorizacije, validacije ili potvrde na tvom poslužitelju.
Kada poslužitelju nedostaju strukturirane informacije potrebne za poziv – poput datuma ili izbora između dvije opcije – može ih zatražiti putem elicitationa, mehanizma MCP protokola. Ograniči ovo na ono što korisnik razumno može pružiti; nikada ga ne koristi za prikupljanje tajni ili zaobilaženje uobičajene autentifikacije.
Više računa i znanje tvrtke
Dvije opcionalne kompatibilnosti poboljšavaju integraciju. Kako bi pomogao korisnicima koji povezuju više računa, izloži alat profila koji je autentificiran, samo za čitanje i označen s _meta["openai/profile"]: true. OpenAI to koristi za identifikaciju povezanih računa i pomoć korisnicima u razlikovanju između njih. Profil se izvodi iz validiranih vjerodajnica zahtjeva, a svaki poziv ostaje ograničen na te vjerodajnice.
Značajka company knowledge (znanje tvrtke) u ChatGPT-u može koristiti tvoje alate samo za čitanje. Da bi dodatak bio prihvatljiv kao izvor, implementiraj standardne sheme ulaza za alate search i fetch, označi ostale alate samo za čitanje s readOnlyHint: true i vrati apsolutne URL-ove koje korisnik može otvoriti za izvore koje model mora citirati.
Implementacija krajnje točke
Javna objava zahtijeva poslužitelj na stabilnoj, javno dostupnoj HTTPS adresi. Ova krajnja točka mora podržavati transport streamable HTTP, odgovarati na stabilnom URL-u (obično završava s /mcp), zadovoljiti zahtjeve latencije i dostupnosti tvojih radnih tijekova, doseći tvoje usluge i podatke, očuvati granice autentifikacije i autorizacije te proizvesti zapise i metrike za neuspjehe inicijalizacije i poziva alata.
OpenAI-jev Secure MCP Tunnel omogućuje povezivanje privatnog poslužitelja s ChatGPT-om, ali ne ispunjava zahtjeve za javnu objavu, kao ni privremeni tunel ili lokalna adresa. Ako poslužitelj mora ostati privatan, postavi javni HTTPS proxy ispred njega: mTLS kojim upravlja OpenAI autentificira ChatGPT kao klijenta, OAuth 2.1 autentificira tvoje korisnike, a popis dopuštenih IP adresa – uključujući raspon koje je OpenAI objavio za ChatGPT konektore, automatski ažuriran – može se dodati, ali nikada ne zamjenjuje autentifikaciju.
Prije lansiranja: ubaci vjerodajnice putem upravitelja tajni tvog hosta, konfiguriraj poslužitelj za autorizaciju i preusmjeravanja, postavi vremenska ograničenja i ograničenja stope za skupe ili javno vidljive alate, ukloni odgovore za otklanjanje pogrešaka i nepotrebne osobne podatke te provjeri da zapisi ne sadrže tokene ili osjetljive rezultate. Nakon implementacije, ponovno pokreni MCP Inspector protiv produkcijske adrese.
Razvoj bez prekida
Zadrži objavljena imena alata i sheme kompatibilnima unatrag: dodaj polja ili alate, ali ne krši postojeće ugovore. Ako se metapodaci promijene, osvježi vezu i ponovno pokreni svoj skup evaluacija prije objave. Za sučelje, promijeni ID resursa kada se HTML, JavaScript ili CSS mijenjaju na način koji bi mogao pokvariti komponentu u predmemoriji.
Podsjetnik na sigurnost
- Svi ulazi alata su nepouzdani: validiraj ih i provedi autorizaciju na poslužitelju
- Zahtijevaj potvrdu za pisanja visokog utjecaja
- Drži tajne i osjetljive podatke izvan metapodataka i rezultata
- Bilježi dovoljno za istragu, ali isključi vjerodajnice i nepotrebne osobne podatke
- Ograniči stopu za skupe ili javno vidljive radnje
Ključne točke
- Imenovani, verzionirani poslužitelj s kratkim, sveobuhvatnim
instructions - Jedan alat po radnji, s naslovom, opisom namjere, shemama, anotacijama i autorizacijom u rukovatelju
structuredContentusklađen sa shemom izlaza,isError: trueza poslovne pogreške, ništa tajno u_meta- Objava: stabilni, javni HTTPS putem streamable HTTP; Secure MCP Tunnel nije dovoljan
- Ugovori kompatibilni unatrag i verzionirani ID-ovi resursa