Przejdź do głównej treści
Polski— Wybierz język
Menu

Serwer MCP: narzędzia, wyniki i wdrożenie

Lekcja 5 z 14 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Serwer, jego tożsamość i instrukcje
  2. Jedno narzędzie na jedną akcję
  3. Przydatne wyniki bez interfejsu
  4. Adnotacje i elicytacja
  5. Wiele kont i wiedza firmowa
  6. Wdrażanie punktu końcowego
  7. Ewolucja bez łamania kompatybilności
  8. Przypomnienia dotyczące bezpieczeństwa
  9. Kluczowe wnioski

Lekcja przepisana 3 listopada 2026 r. na podstawie strony Build an MCP server z dokumentacji wtyczek OpenAI oraz kodu MCP TypeScript SDK (wersja 1.32.2). Poprzednia lekcja opisywała „akcje“ (defineAction, ActionError) pochodzące z nieistniejącego SDK; rolę tę przejęły obecnie narzędzia MCP. Źródła: Build an MCP server · MCP TypeScript SDK.

Serwer, jego tożsamość i instrukcje

Utwórz serwer MCP ze stabilną nazwą i wersją. Podczas inicjalizacji może on również zwracać pole instructions, które ChatGPT i Codex odczytują wraz z metadanymi narzędzi. Przeznacz to pole na wytyczne obowiązujące dla wszystkich narzędzi – takie jak obowiązkowa kolejność wywołań czy wspólny limit częstotliwości – i utrzymaj główną treść w pierwszych 512 znakach. Nie kopiuj tutaj opisów narzędzi i nie próbuj zmieniać osobowości 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.",
  }
);

Jedno narzędzie na jedną akcję

Utwórz osobne narzędzie dla każdej odrębnej akcji: list_projects, get_project, update_project, zamiast jednego uniwersalnego narzędzia z licznymi trybami. Każde narzędzie łączy nazwę wskazującą na akcję, czytelny tytuł, opis wyjaśniający, kiedy go użyć, jawny schemat wejścia, schemat wyjścia (jeśli zwraca dane strukturalne), precyzyjne adnotacje oraz obsługę, która autoryzuje żądanie przed podjęciem działania. Model polega na tych metadanych, aby zdecydować, czy i jak wywołać narzędzie – traktuj je jako część doświadczenia użytkownika.

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

Funkcje authenticate i loadProject to Twoje własne implementacje. Kluczowa jest ich lokalizacja: autoryzacja odbywa się po stronie serwera, przy każdym żądaniu. Nigdy nie polegaj na modelu w kwestii decydowania, czy użytkownik ma uprawnienia do dostępu do danych.

Przydatne wyniki bez interfejsu

Wynik działania narzędzia może zawierać trzy elementy:

  • structuredContent: zwięzłe dane, które model może przeanalizować i wykorzystać w kolejnych wywołaniach;
  • content: tekst lub inne treści MCP pomagające modelowi udzielić odpowiedzi;
  • _meta: dane przeznaczone dla klienta, ukryte przed modelem.

Zwracaj wystarczającą ilość informacji, aby model mógł dokończyć zadanie bez komponentu wizualnego, używając stabilnych identyfikatorów, które kolejne narzędzia będą mogły ponownie wykorzystać. Warto zwrócić uwagę na dwa zachowania SDK. Narzędzie deklarujące outputSchema musi zwracać zgodne structuredContent we wszystkich pomyślnych wynikach; w przeciwnym razie SDK zgłosi błąd walidacji. Błąd biznesowy – taki jak brak projektu lub odmowa wykonania akcji – sygnalizowany jest wynikiem z isError: true wraz z wyjaśniającym tekstem, który model może przekazać użytkownikowi; ten typ wyniku pomija walidację schematu wyjścia.

Nigdy nie dołączaj do wyniku sekretów, tokenów dostępu ani niepotrzebnych danych osobowych i nie traktuj _meta jako bezpiecznej kryjówki: pole to jest ukryte przed modelem, ale nie jest chronione.

Adnotacje i elicytacja

Adnotacje muszą odzwierciedlać rzeczywiste zachowanie narzędzia: ustaw readOnlyHint na true tylko wtedy, gdy narzędzie nie może niczego modyfikować, destructiveHint na true, jeśli może spowodować nieodwracalny lub trudny do cofnięcia skutek, oraz openWorldHint na true, jeśli dotyczy publicznego internetu lub otwartych podmiotów zewnętrznych. Pomagają one ChatGPT i Codex wybrać odpowiednie zachowanie potwierdzające; nie zastępują one jednak logiki autoryzacji, walidacji ani potwierdzania po stronie Twojego serwera.

Gdy serwer potrzebuje strukturalnych informacji brakujących w wywołaniu – takich jak data lub wybór między dwiema opcjami – może zażądać ich poprzez elicytację, mechanizm protokołu MCP. Ogranicz to do tego, co użytkownik może rozsądnie dostarczyć; nigdy nie używaj tego do zbierania sekretów ani omijania standardowej autentyfikacji.

Wiele kont i wiedza firmowa

Dwie opcjonalne kompatybilności poprawiają integrację. Aby pomóc użytkownikom łączącym wiele kont, udostępnij narzędzie profilowe, które jest uwierzytelnione, tylko do odczytu i oznaczone jako _meta["openai/profile"]: true. OpenAI wykorzystuje to do identyfikacji połączonych kont i pomagania użytkownikom w rozróżnianiu ich. Profil jest wyprowadzany ze zweryfikowanych poświadczeń żądania, a każde wywołanie pozostaje ograniczone do tych poświadczeń.

Funkcja company knowledge w ChatGPT może wykorzystywać narzędzia tylko do odczytu z Twojego serwera. Aby wtyczka kwalifikowała się jako źródło, zaimplementuj standardowe schematy wejścia dla narzędzi search i fetch, oznacz inne narzędzia tylko do odczytu flagą readOnlyHint: true i zwracaj bezwzględne adresy URL, które użytkownik może otworzyć, dla źródeł, które model musi cytować.

Wdrażanie punktu końcowego

Publiczne zgłoszenie wymaga serwera pod stabilnym, publicznie dostępnym adresem HTTPS. Ten punkt końcowy musi obsługiwać transport streamable HTTP, odpowiadać pod stabilnym adresem URL (zazwyczaj kończącym się na /mcp), spełniać wymagania dotyczące opóźnień i dostępności Twoich przepływów pracy, osiągać Twoje usługi i dane, zachowywać granice autentyfikacji i autoryzacji oraz generować dzienniki i metryki dotyczące niepowodzeń inicjalizacji i wywołań narzędzi.

Secure MCP Tunnel od OpenAI pozwala połączyć prywatny serwer z ChatGPT, ale nie spełnia wymagań publicznego zgłoszenia, podobnie jak tymczasowy tunel lub adres lokalny. Jeśli serwer musi pozostać prywatny, umieść przed nim publiczny proxy HTTPS: mTLS zarządzane przez OpenAI uwierzytelnia ChatGPT jako klienta, OAuth 2.1 uwierzytelnia Twoich użytkowników, a można dodać listę dozwolonych adresów IP – obejmującą zakresy opublikowane przez OpenAI dla konektorów ChatGPT, aktualizowane automatycznie – ale nigdy nie zastępuje ona autentyfikacji.

Przed uruchomieniem: wstrzyknij poświadczenia poprzez menedżera sekretów swojego hosta, skonfiguruj serwer autoryzacji i przekierowania, ustaw limity czasu i częstotliwości dla kosztownych lub widocznych zewnętrznie narzędzi, usuń odpowiedzi debugowe i niepotrzebne dane osobowe oraz upewnij się, że dzienniki nie zawierają tokenów ani wrażliwych wyników. Po wdrożeniu odtwórz MCP Inspector przeciwko adresowi produkcyjnemu.

Ewolucja bez łamania kompatybilności

Utrzymuj opublikowane nazwy narzędzi i schematy zgodne wstecz: dodawaj pola lub narzędzia, ale nie łam istniejących kontraktów. Jeśli metadane ulegną zmianie, odśwież połączenie i ponownie uruchom swój zestaw ewaluacji przed zgłoszeniem. W przypadku interfejsu zmień identyfikator zasobu, gdy HTML, JavaScript lub CSS ewoluują w sposób, który mógłby uszkodzić buforowany komponent.

Przypomnienia dotyczące bezpieczeństwa

  • Wszystkie dane wejściowe narzędzi są niezaufane: waliduj je i wymuszaj autoryzację na serwerze
  • Wymagaj potwierdzenia dla operacji zapisu o wysokim wpływie
  • Trzymaj sekrety i dane wrażliwe z dala od metadanych i wyników
  • Loguj wystarczająco dużo, aby móc przeprowadzić dochodzenie, ale wyklucz poświadczenia i niepotrzebne dane osobowe
  • Stosuj limitowanie częstotliwości dla kosztownych lub widocznych zewnętrznie akcji

Kluczowe wnioski

  • Nazwany, wersjonowany serwer z krótkimi, przekrojowymi instructions
  • Jedno narzędzie na akcję, z tytułem, opisem intencji, schematami, adnotacjami i autoryzacją w obsłudze
  • structuredContent zgodne ze schematem wyjścia, isError: true dla błędów biznesowych, nic tajnego w _meta
  • Publikacja: stabilne, publiczne HTTPS poprzez streamable HTTP; Secure MCP Tunnel jest niewystarczające
  • Kontrakty zgodne wstecz i wersjonowane identyfikatory zasobów