MCP dla początkujących: stworzenie serwera i klienta, a następnie ich zastosowanie w środowisku korporacyjnym.
MCP dla początkujących: problem N x M, podstawowe koncepcje w prostych słowach, serwer i klient pomocowy w TypeScript dla Node.js oraz przejście do bezpiecznych implementacji HTTP.
Źródła: MCP Tools Inside Enterprise Applications: A Beginner-Friendly Deep Dive
Każdy, kto ostatnio pracował z agentami AI, natknął się na MCP – Model Context Protocol. Pojawia się on w Claude Desktop, w pluginach do IDE, w projektach „portalu AI” wewnętrznego używanego przez firmy, a coraz częściej także w profesjonalnym oprogramowaniu przemysłowym.
To wprowadzenie na poziomie początkującego, które nie zakłada żadnego wcześniejszego doświadczenia z MCP. Zaczyna się od problemu, który rozwiązuje ten protokół, omawia jego architekturę, tworzy rzeczywisty serwer i klient w TypeScript na Node.js, a następnie przygląda się kwestiom bezpieczeństwa, zarządzania i możliwości monitorowania, które firmy stosują w związku z tym rozwiązaniem. Diagramy są w formacie prostego tekstu ASCII, więc można je bezpośrednio wkleić do notatek lub dokumentacji kodu.
1. Problem, który rozwiązuje MCP
Przed MCP, aby agent mógł wykonać jakąś rzeczywistą czynność, taką jak odczytanie rekordu z CRM, otwarcie zgłoszenia w ITSM czy zapytanie do magazynu danych, oznaczało to dokładnie jedno: konieczność napisania specjalistycznego, jednorazowego kodu integracyjnego dla danego agenta i danego systemu.
To jest jeszcze do przyjęcia, dopóki istnieje kilka agentów (bot obsługi klienta, asystent programistyczny, wewnętrzny pomocnik wiedzy) oraz kilka systemów (Salesforce, Jira, baza danych HR, magazyn). W rezultacie powstaje zbiór kombinacyjnych, ręcznie stworzonych połączeń.
BEFORE MCP — the N x M integration problem
┌───────────┐ ┌─────────────┐
│ Agent A │───────▶│ CRM API │ (custom connector #1)
└───────────┘ └─────────────┘
┌───────────┐ ┌─────────────┐
│ Agent A │───────▶│ Ticketing │ (custom connector #2)
└───────────┘ └─────────────┘
┌───────────┐ ┌─────────────┐
│ Agent B │───────▶│ CRM API │ (custom connector #3 -
└───────────┘ └─────────────┘ yes, AGAIN, for a different agent)
┌───────────┐ ┌─────────────┐
│ Agent B │───────▶│ Data │ (custom connector #4)
└───────────┘ │ Warehouse │
└─────────────┘
N agents x M systems = N x M custom, non-reusable integrations.
Every new agent re-implements auth, retries, schemas, error handling.
USB rozwiązał ten sam rodzaj problemu w przypadku urządzeń peryferyjnych, a ODBC i JDBC zrobili to dla baz danych: zbyt wiele specjalnych konektorów i brak wspólnego standardu. MCP to odpowiedź Anthropic, opublikowana jako otwarty protokół, a nie funkcja dostępna tylko w Claude, dzięki czemu każda aplikacja AI i każdy backend mogą używać wspólnego języka.
AFTER MCP — one protocol, many servers, many clients
┌───────────┐ ┌───────────────────┐
│ Agent A │──┐ ┌─▶│ MCP Server: CRM │
└───────────┘ │ ┌───────────┐ │ └───────────────────┘
├───▶│ MCP │───┤ ┌───────────────────┐
┌───────────┐ │ │ (shared │ ├─▶│ MCP Server: Ticket │
│ Agent B │──┘ │ protocol)│ │ └───────────────────┘
└───────────┘ └───────────┘ │ ┌──────────────────┐
└─▶│ MCP Server: DW │
└──────────────────┘
Any MCP-compatible agent can now talk to any MCP server.
Build the connector once, reuse it everywhere.
Opis mieści się w jednym zdaniu. MCP zapewnia aplikacjom AI jedną wspólną metodę na znajdowanie narzędzi, wywoływanie ich, odczytywanie danych oraz korzystanie z szablonów promptów, dzięki czemu integracja jest pisana raz, a każdy zgodny klient może ją ponownie wykorzystać.
2. Podstawowe koncepcje w prostych słowach
Cztery terminy są używane w sposób nieprecyzyjny, więc zostają zdefiniowane przed napisaniem jakiegokolwiek kodu.
- Host. Aplikacja wykorzystująca AI, z którą ma bezpośredni kontakt użytkownik końcowy, np. wewnętrzny asystent do czatowania, wtyczka IDE lub kopilot do obsługi klienta, i to właśnie ona zawiera model językowy LLM.
- Klient MCP. Komponent wewnątrz hosta, który zarządza pojedynczym połączeniem z konkretnym serwerem MCP. Host komunikujący się z trzema backendami zazwyczaj uruchamia trzy takie klienty, po jednym na każdy serwer.
Poniżej wszystkie wiadomości wykorzystują JSON-RPC 2.0 – prosty i powszechnie stosowany format do przesyłania zapytań, odpowiedzi oraz powiadamień. SDK generuje go za Ciebie, ale znajomość tego formatu wyjaśnia, dlaczego narzędzia do debugowania MCP przypominają narzędzia API, których już używasz, zawierając ID zapytania, nazwę metody, parametry oraz wynik lub błąd.
Co może zaoferować serwer: trzy elementy bazowe
- Narzędzia to funkcje, które można wywołać, umożliwiające modelowi działanie lub pobieranie obliczonych wyników; to model decyduje, kiedy je wywołać, w zależności od żądania użytkownika. Przykłady:
create_support_ticket,get_employee_details. - Zasoby to dane tylko do odczytu, które host może dołączyć jako kontekst, np. pliki lub rekordy. To aplikacja lub użytkownik decyduje, co dołączyć. Przykłady: artykuł z bazy wiedzy, plik PDF z zasadami, plik logów.
W większości integracji korporacyjnych narzędzia realizują około 90% istotnej pracy, dlatego są budowane jako pierwsze.
3. Architektura – trzy warstwy razem
┌─────────────────────────── HOST APPLICATION ───────────────────────────┐
│ e.g. an internal AI assistant, IDE plugin, support copilot │
│ │
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
│ │ MCP Client 1 │ │ MCP Client 2 │ │ MCP Client 3 │ │
│ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘ │
└───────────┼────────────────────────┼───────────────────────┼───────────┘
│ JSON-RPC over │ JSON-RPC over │ JSON-RPC over
│ stdio / HTTPS │ stdio / HTTPS │ stdio / HTTPS
▼ ▼ ▼
┌──────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ MCP Server │ │ MCP Server │ │ MCP Server │
│ wraps HR system │ │ wraps Ticketing │ │ wraps Data │
│ (tools: lookup, │ │ (tools: create, │ │ Warehouse │
│ update) │ │ status, close) │ │ (tools: query) │
└──────────────────┘ └──────────────────┘ └─────────────────┘
Każdy serwer MCP powinien być mały i skoncentrowany, z oddzielnym serwerem dla każdego systemu backendowego, bez jednego ogromnego serwera obsługującego wszystko. Ten podejście jest zapożyczone z mikrosług, charakteryzujących się małym zasięgiem wpływu, niezależną implementacją, niezależną skalowalnością oraz odpowiedzialnością zespołu odpowiedzialnego za dany backend.
4. Budowa pierwszego serwera MCP (Node.js i TypeScript)
Przykładem jest serwer MCP do obsługi klientów IT zawierający dwa narzędzia: jedno do tworzenia zgłoszeń wsparcia, a drugie do sprawdzania statusu zgłoszenia. Odzwierciedla to bardzo powszechny wzorzec w przedsiębiorstwach, polegający na wykorzystaniu wewnętrznej API do zarządzania zgłoszeniami lub ITSM.
4.1 Konfiguracja projektu
mkdir helpdesk-mcp-server && cd helpdesk-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript tsx @types/node
npx tsc --init
@modelcontextprotocol/sdk to oficjalny pakiet. Zajmuje się przesyłaniem danych w formacie JSON-RPC, transportami oraz elementami podstawowymi, dzięki czemu surowy format JSON-RPC nigdy nie jest edytowany ręcznie. zod to biblioteka do walidacji schematów. Dane wprowadzane przez narzędzia MCP są sprawdzane pod kątem zgodności ze schematem przed uruchomieniem kodu obsługującego, co ma ogromne znaczenie w środowiskach korporacyjnych, ponieważ błędne lub złośliwe żądania są blokowane na wstępie.
4.2 Kod serwera
// src/server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
// --- A stand-in for a real internal ticketing API client ---
// In a real enterprise server this would call your ITSM system
// (ServiceNow, Jira Service Management, Zendesk, an internal API, etc.)
const ticketStore = new Map<string, { status: string; subject: string }>();
let nextId = 1000;
// 1. Create the server instance.
// "name" and "version" identify this server to any client that connects.
const server = new McpServer({
name: "helpdesk-mcp-server",
version: "1.0.0",
});
// 2. Register a tool: create_support_ticket
server.registerTool(
"create_support_ticket",
{
title: "Create Support Ticket",
description:
"Creates a new IT helpdesk ticket for the requesting employee.",
inputSchema: {
subject: z.string().describe("Short summary of the issue"),
priority: z.enum(["low", "medium", "high", "urgent"]),
employeeId: z.string().describe("Requesting employee's ID"),
},
outputSchema: {
ticketId: z.string(),
status: z.string(),
},
},
async ({ subject, priority, employeeId }) => {
const ticketId = `TCK-${nextId++}`;
ticketStore.set(ticketId, { status: "open", subject });
const output = { ticketId, status: "open" };
// MCP tool results return a "content" array (what a human/LLM reads)
// and, optionally, "structuredContent" (typed data other code can use).
return {
content: [
{
type: "text",
text: `Created ticket ${ticketId} (priority: ${priority}) for employee ${employeeId}.`,
},
],
structuredContent: output,
};
}
);
// 3. Register a second tool: get_ticket_status
server.registerTool(
"get_ticket_status",
{
title: "Get Ticket Status",
description: "Looks up the current status of an existing support ticket.",
inputSchema: {
ticketId: z.string(),
},
outputSchema: {
status: z.string(),
},
},
async ({ ticketId }) => {
const ticket = ticketStore.get(ticketId);
if (!ticket) {
// Returning isError lets the model know the call failed
// WITHOUT crashing the whole conversation.
return {
content: [{ type: "text", text: `No ticket found with ID ${ticketId}.` }],
isError: true,
};
}
return {
content: [{ type: "text", text: `Ticket ${ticketId} is currently "${ticket.status}".` }],
structuredContent: { status: ticket.status },
};
}
);
// 4. Wire the server to a transport and start listening.
// stdio is perfect for local development and desktop-hosted tools.
const transport = new StdioServerTransport();
await server.connect(transport);
4.3 Co robi każda część
- Instancja
McpServer. Ten obiekt stanowi serce serwera. Śledzi każdy zarejestrowany narzędzie, zasób i polecenie, a także obsługuje procedurę handshake MCP (negocjację możliwości) po połączeniu się klienta. Lista narzędzi nigdy nie jest tworzona ręcznie, ponieważ SDK buduje ją na podstawie wywołańregisterTool. inputSchemaz Zod. To coś więcej niż tylko dokumentacja. SDK wykorzystuje go do generowania JSON Schema, które informuje klienta i model LLM o dostępnych argumentach, a także do weryfikacji każdego przychodzącego wywołania. Klient, który przesyłapriority: „banana”, jest odrzucany jeszcze przed dotarciem do obsługi. Dla przedsiębiorstw ta weryfikacja oparta na schemacie jest istotną kontrolą bezpieczeństwa, a nie tylko dodatkowym udogodnieniem.
outputSchema i structuredContent. Narzędzie może zwrócić podsumowanie czytelne dla człowieka (content) oraz obiekt czytelny dla maszyny (structuredContent). Tekst pojawia się w transkrypcji rozmowy, natomiast aplikacja wywołująca może przetworzyć strukturyzowane dane w celu obsługi interfejsu użytkownika lub dalszej logiki.isError: true. MCP definiuje błąd na poziomie narzędzia jako odrębną kategorię od błędu na poziomie protokołu. Oznacza to, że operacja nie powiodła się, ale rozmowa powinna być kontynuowana – model może więc przeczytać błąd i zdecydować, czy spróbować ponownie, zapytać użytkownika lub użyć innego narzędzia. Nie chcesz, aby cała sesja agenta upadła z powodu braku istnienia jakiegoś identyfikatora zlecenia.StdioServerTransport). Element odpowiedzialny za przesyłanie bajtów. W przypadku narzędzi lokalnych, takich jak IDE programisty czy asystent biurowy, najprostszym rozwiązaniem jest standardowe stdio, przy którym host uruchamia serwer jako proces potomny. Wszystko, co działa centralnie w przedsiębiorstwie, wykorzystuje transport oparty na HTTP, o którym mowa w Sekcji 6.4.4 Uruchamianie
npx tsx src/server.ts
Sam w sobie serwer nic nie pokazuje, ponieważ czeka na połączenie z klientem przez stdin i stdout. Następnie przychodzi klient.
5. Klient w aplikacji korporacyjnej
Początkujący często tworzą serwer, a potem zastanawiają się, co tak naprawdę z nim komunikuje się. Oto minimalny klient, wyobrażony jako część wewnętrznego backendu Node.js, który napędza asystenta AI firmy.
// src/client.ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
async function main() {
// 1. Describe how to launch the server. Here we spawn it as a
// local subprocess - in production you'd more commonly point
// this at a remote HTTP-based server instead (see Section 6).
const transport = new StdioClientTransport({
command: "npx",
args: ["tsx", "src/server.ts"],
});
// 2. Create a client and connect. This performs the MCP
// handshake and capability negotiation automatically.
const client = new Client({ name: "internal-ai-assistant", version: "1.0.0" });
await client.connect(transport);
// 3. Discover what tools this server offers - this is the same
// mechanism an LLM uses to "learn" what it can do.
const { tools } = await client.listTools();
console.log("Available tools:", tools.map((t) => t.name));
// 4. Call a tool, just like the LLM would.
const result = await client.callTool({
name: "create_support_ticket",
arguments: {
subject: "VPN keeps disconnecting",
priority: "high",
employeeId: "E-4821",
},
});
console.log(result.content);
await client.close();
}
main();
Dlaczego ma to znaczenie koncepcyjne
Główną ideą jest odkrywanie. Klient wywołuje funkcję listTools() i otrzymuje maszynowo czytelny katalog wszystkiego, co oferuje serwer, przy czym każde narzędzie ma swoją specyfikację. To właśnie sprawia, że MCP jest dynamiczne: host oparty na LLM nie musi mieć narzędzi wbudowanych w swoje polecenie. Podczas nawiązywania połączenia pyta serwer o to, co może robić, a odpowiedź staje się częścią informacji przekazywanych modelowi na temat możliwych działań w danej rozmowie.
Bezpieczeństwo i zarządzanie w przedsiębiorstwach opierają się dokładnie na tym mechanizmie. Jeśli dane narzędzie nie powinno być dostępne dla określonego użytkownika lub środowiska, najskuteczniejszą formą kontroli jest wykluczenie go z wyników funkcji listTools(), zamiast liczyć na to, że model sam zdecyduje się go nie używać.
6. Przejście od lokalnego prototypu do wdrożenia w firmie
Ustawienie stdio nadaje się do nauki i używania lokalnych narzędzi deweloperskich, ale nie odpowiada sposobowi, w jaki większość przedsiębiorstw zarządza infrastrukturą: jest hostowana centralnie, chroniona przez mechanizmy autoryzacji, ma zapisy logów i jest dostępna dla wielu aplikacji jednocześnie. Właśnie tu przydają się transport Streamable HTTP oraz brama API.
Oto ten sam serwer helpdesk dostosowany do działania przez HTTP i umieszczony za zwykłą aplikacją Express:
// src/httpServer.ts
import express from "express";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
const app = express();
app.use(express.json());
app.post("/mcp", async (req, res) => {
// In a real enterprise deployment, authentication middleware would
// run BEFORE this point - verifying a bearer token, checking scopes,
// and attaching the caller's identity to the request.
const server = buildHelpdeskServer(); // same registerTool calls as before
const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: undefined, // stateless mode: simplest to scale horizontally
});
res.on("close", () => transport.close());
await server.connect(transport);
await transport.handleRequest(req, res, req.body);
});
app.listen(3000, () => console.log("MCP server listening on :3000"));
Znacząca zmiana dotyczy raczej miejsca, gdzie leży odpowiedzialność, niż samego kodu. Trzy kwestie, które były domyślne w stdio, stają się wyraźnymi problemami przedsiębiorstwa w kontekście HTTP.
- Autoryzacja odbywa się przed serwerem, zazwyczaj w warstwie middleware lub bramce, co pozwala serwerowi zakładać, że
reqzawiera już zweryfikowaną tożsamość. - Brak stanu to świadoma decyzja. Przy użyciu
sessionIdGenerator: undefinedtransport nie przechowuje żadnego stanu sesji dla poszczególnych połączeń, więc dowolna instancja za load balancerem może odpowiedzieć na każde żądanie, a aplikację można skalować tak jak każdą API bez stanu. - Obserwowalność przestaje być opcjonalna. Każde wywołanie narzędzia stanowi rzeczywiste żądanie sieciowe, więc powinno być rejestrowane, śledzone i ograniczane pod względem częstotliwości tak samo jak każde wewnętrzne wywołanie API.
7. Lista kontrolna kwestii związanych z przedsiębiorstwem
Uruchomienie serwera MCP to zaledwie piąta część zadania. Pozostałe cztery piąte to zapewnienie jego bezpieczeństwa w środowiskach produkcyjnych, które przechowują rzeczywiste dane pracowników lub klientów, a ta część wygląda następująco.
- Autoryzacja i uwierzytelnianie. Wykorzystaj OAuth2 lub OIDC w bramce. Powiąż tożsamość użytkownika lub konta usługowego z konkretnymi uprawnieniami, aby nie każde narzędzie mogło być wywoływane przez każdego użytkownika.
- Projektowanie narzędzi z minimalnymi uprawnieniami. Woląć wąsko specjalistyczne narzędzia, takie jak
get_ticket_status, zamiast szeroko zakrojonych, takich jakrun_sql_query. Narzędzie, które wykonuje jedną dobrze zdefiniowaną funkcję, jest znacznie łatwiejsze do zrozumienia i audytowania.
8. Gdzie to występuje w rzeczywistych przedsiębiorstwach
- IT i wsparcie wewnętrzne. Przykład stanowiska pomocy: tworzenie i wyszukiwanie zgłoszeń, resetowanie haseł, sprawdzanie stanu systemu.
- Asystenci sprzedaży i CRM. Pobieranie historii kont i tworzenie projektów e-maili w oparciu o rzeczywiste dane CRM, a nie o domysły modelu.
- Asystenci do pracy z danymi i analiz. Zestaw narzędzi do zapytań o dostępie tylko do odczytu, uprzednio zatwierdzonych, do pracy z bazą danych, zamiast nieograniczonego SQL.
- Procesy w ochronie zdrowia. Narzędzia, które sprawdzają dostępne terminy wizyt, weryfikują uprawnienia ubezpieczeniowe lub wykrywają braki w koordynacji opieki, zawsze działają pod ścisłym kontrolowaniem dostępu opartego na rolach oraz z pełnymi śladami audytowymi ze względu na wrażliwość danych. Tutaj zasady ograniczonego zakresu narzędzi, udziału człowieka oraz pełnego rejestrowania działań z sekcji 7 są często wymogiem przestrzegania regulacji.
- Narzędzia dla programistów. Asystenci w środowiskach IDE, które wyszukują informacje w wewnętrznej dokumentacji, uruchamiają procesy CI lub sprawdzają, kto jest na dyżurze w danym serwisie.
To, co łączy te przypadki: MCP nie czyni modelu mądrzejszym. Zmienia się to, że sztuczna inteligencja uzyskuje uzasadniony, kontrolowany dostęp do rzeczywistych systemów i nie musi już wymyślać wiarygodnie brzmiących odpowiedzi.
9. Pułapki, na które natrafiają początkujący
- Jeden ogromny serwer „robiący wszystko”. Podzielony na systemy backendowe lub domeny. To odzwierciedla dobre granice mikrosług i ogranicza zasięg skutków awarii.
- Pomijanie pól
description. Model w dużej mierze polega na opisach narzędzi i parametrów, aby decydować, kiedy i jak coś wywołać. Niejasne opisy prowadzą do wyboru niewłaściwego narzędzia lub właściwego narzędzia z niewłaściwymi argumentami. - Zapominanie o
isError. Surowy błąd rzucony przez obsługę narzędzia może sparaliżować całe połączenie klienta, podczas gdy model powinien otrzymać informację o niepowodzeniu i spróbować czegoś innego. - Wprowadzanie stdio do środowiska produkcyjnego. Stdio nadaje się do lokalnego rozwoju i komputerów stacjonarnych. Środowisko produkcyjne dla wielu użytkowników wymaga transportu HTTP za pomocą prawdziwego bramy.
10. Wersja skrócona
Gdy usuniemy wszystkie modne terminy, podstawowa idea MCP okazuje się zaskakująco prosta: jedna wspólna metoda umożliwiająca aplikacjom opartym na sztucznej inteligencji znajdowanie i wywoływanie narzędzi, pobieranie danych oraz ponowne wykorzystywanie szablonów zapytań, co oznacza, że praca nad integracją wykonywana raz służy wszystkim klientom spełniającym wymogi. Dla przedsiębiorstw to właśnie standaryzacja pozwala przekształcić agenty sztucznej inteligencji z efektownych demonstracji w rozwiązania, które można zarządzać, zabezpieczać i używać w środowisku produkcyjnym obok wszystkich innych aplikacji.
Dla osób rozpoczynających pracę rozsądną drogą jest:
- Zbudowanie lokalnego, małego serwera MCP przy użyciu stdio, podobnie jak w przykładzie z obsługą klienta.
- Dodanie klienta, który wywołuje te narzędzia, aby cała ścieżka działania była widoczna.
- Umieść serwer za protokołem HTTP z autoryzacją lub bramką przed nim.
- Dopiero wtedy zastosuj rejestrację działań, limity szybkości oraz ludzką aprobatę dla wszelkich działań destruktywnych.
Zacznij od małych, lokalnych rozwiązań i stopniowo wprowadzaj kwestie związane z przedsiębiorstwem. Próba stworzenia idealnego serwera produkcyjnego od samego początku to o wiele mniej pewny sposób osiągnięcia celu.