MCP wyjaśnione: stworzenie asystenta do PostgreSQL w języku naturalnym dla Claude.

Problem kodu łączącego

W pewnym momencie każdy programista tworzący produkty AI napotyka ten sam problem. Model jest sprawny, a użyteczne dane znajdują się w bazie danych, systemie plików lub jakiejś API. Brakuje jednak czystego, standardowego sposobu na połączenie tych dwóch elementów.

Dlatego pojawia się kod łączący: adapter tu, kruchy obudowie tam. Działa to do chwili, gdy model ulega zmianie, pojawia się drugie źródło danych lub nowy kolega z zespołu musi przeprojektować całą warstwę obsługi danych.

Odpowiedź Anthropic nadeszła w listopadzie 2024 roku w postaci Model Context Protocol (MCP). W ciągu zaledwie dwóch lat przekształcił się on z eksperymentu typu niszowego w standardową infrastrukturę dla agentów: do połowy 2026 roku odnotowano 97 milionów pobierania SDK miesięcznie oraz prawie 10 000 aktywnych publicznych serwerów w oficjalnym rejestrze.

Rozważmy produkt, w którym użytkownicy zadają pytania dotyczące danych firmy w prostym języku angielskim. Pomysł jest prosty, ale jego realizacja jest trudna. System musi zinterpretować pytanie, przekształcić je w zapytanie do bazy danych, je wykonać, przekazać wyniki modelowi i sformatować odpowiedź. Pomnóż to przez każde narzędzie, z którym powinna współpracować sztuczna inteligencja – takie jak kalendarz, repozytorium na GitHubie czy przestrzeń robocza w Slacku – a każde z nich staje się odrębną integracją z własnymi formatami API, procedurami autoryzacji i formatami błędów.

Część inżynierów nazywa taki stan rzeczy „integracją spaghetti”. Jeśli liczba modeli to N, a narzędzi M, to każda kombinacja wymaga odrębnego kodu. Dodanie kolejnego modelu wymaga przeróbki wszystkich narzędzi, natomiast dodanie kolejnego narzędzia oznacza konieczność aktualizacji integracji każdego modelu.

Czym jest MCP

MCP to otwarty standard oparty na JSON-RPC 2.0, który zapewnia modelom wspólną bazę słownictwa umożliwiającą dostęp do zewnętrznych narzędzi i danych. Struktura N × M zmienia się na N + M, ponieważ jeden serwer może obsługiwać każdego klienta, który stosuje ten protokół.

Najczęściej używaną analogią jest USB-C. Kable do ładowania były wcześniej różne w zależności od laptopów, telefonów, aparatów i słuchawek – każdy wymagał własnego kabla. USB-C zmienił tylko złącze, a nie sposób przesyłania prądu, dzięki czemu jeden kabel wystarcza do wszystkiego. MCP pełni tę samą rolę w przypadku sztucznej inteligencji: model, który rozumie ten protokół, może korzystać z dowolnego narzędzia, które go obsługuje, więc serwer napisany raz będzie działał z każdym kompatybilnym modelem.

Rządy doprowadziły do tego, że rok 2026 stał się punktem zwrotnym. W grudniu 2025 roku Anthropic przekazał MCP fundacji Agentic AI Foundation – specjalnemu funduszowi działającemu w ramach Linux Foundation, który wspólnie założyły Anthropic, Block i OpenAI – co wskazywało, że protokół nie należy już wyłącznie do Anthropic. Nastąpiło publiczne poparcie: dyrektor generalny OpenAI go poparł i ogłosił wsparcie dla SDK agentów oraz ChatGPT, a Google DeepMind w ciągu kilku dni potwierdziło, że Gemini będzie używać MCP do swoich narzędzi. Protokół ten jest obecnie standardową ścieżką łączącą modele z zewnętrznymi narzędziami, danymi i usługami.

Trzy komponenty

Hosita to aplikacja, z którą faktycznie ma kontakt użytkownik: Claude Desktop, rozszerzenie VS Code lub wewnętrzny chatbot.

Klient MCP znajduje się w hostingu. Utrzymuje otwarte połączenia z jednym lub więcej serwerami MCP i kieruje wiadomości pomiędzy modelem a tymi serwerami, dzięki czemu gdy model postanowi wywołać narzędzie, klient przekazuje żądanie.

Serwer MCP to miejsce, w którym znajdują się możliwości realizacji zadań. Każdy serwer otacza narzędzie lub źródło danych standardową interfejsem i może oferować trzy rodzaje elementów:

• Narzędzia to funkcje, które można wywołać, takie jak run_sql_query, search_web lub send_email. Model wykorzystuje je do podejmowania działań lub pobierania danych.
• Zasoby to dane, które można odczytać, takie jak pliki, wiersze w bazie danych lub dokumenty, które model może włączyć do swojego okna kontekstowego.
• Wzory promptów to szablony promptów, które można wielokrotnie używać i które serwer przekazuje hostowi.

Wiadomości są kodowane w formacie JSON-RPC 2.0 i przekazywane za pomocą jednego z dwóch mechanizmów transmisji. stdio nadaje się do serwerów działających jako procesy lokalne na komputerze klienta. Streamable HTTP jest przeznaczony dla serwerów zdalnych i rozwiązań chmurowych, wykorzystując zwykłe żądania HTTP oraz opcjonalnie Server-Sent Events (SSE) do przesyłania odpowiedzi w formie strumieni i powiadamień od serwera do klienta. Dzięki temu podziałowi jeden protokół obejmuje zarówno rozwój lokalny, jak i systemy w skali produkcyjnej.

Jedno pytanie, krok po kroku

Oto, co dzieje się od chwili, gdy użytkownik wpisuje pytanie, do momentu otrzymania odpowiedzi.

1. Użytkownik pyta: „Ile zamówień mieliśmy w zeszłym tygodniu?”
2. Model widzi to pytanie obok listy dostępnych narzędzi, pobranych z serwera MCP przy uruchamianiu.
3. Decyduje, że potrzebna jest funkcja query_database, i wysyła strukturyzowane żądanie do tego narzędzia.
4. Klient MCP przechwytuje żądanie i wysyła je do odpowiedniego serwera.
5. Serwer wykonuje zapytanie i zwraca wynik w formacie JSON.
6. Model odczytuje ten wynik i pisze odpowiedź w języku potocznym.

Model w ogóle nie ma dostępu do samej bazy danych, a także nie potrzebuje uprzednio ciągu połączenia, ponieważ serwer MCP zajmuje się tym wszystkim.

Projekt: interfejs czatowy dla PostgreSQL

Pomijając teorię, oto coś konkretnego. Zespół przechowuje swoje dane dotyczące zamówień w PostgreSQL, a koledzy niebędący specjalistami technicznymi ciągle proszą jedyną osobę znającą SQL o przygotowanie raportów. Celem jest interfejs czatowy, w którym mogliby zadawać pytania w prostym języku angielskim i otrzymywać natychmiastowe odpowiedzi bez konieczności pisania żadnego kodu SQL.

Plan zakłada istnienie serwera MCP przed bazą danych PostgreSQL, który oferuje jedno narzędzie query_database i jest połączony z Claude. Każdy z zespołu może wtedy zadać pytanie w języku potocznym i otrzymać rzeczywiste dane.

Ustawianie

Zacznij od nowej folderu projektu i zainstaluj wymagane zależności.

mkdir nl-db-assistant
cd nl-db-assistant
npm init -y
npm install @modelcontextprotocol/sdk pg dotenv zod

Pakiety dzielą pracę między siebie. @modelcontextprotocol/sdk to oficjalny zestaw JavaScript i TypeScript od Anthropic przeznaczony do serwerów MCP, pg to standardowy klient PostgreSQL dla Node.js, a dotenv zapobiega umieszczaniu haseł do bazy danych w kodzie źródłowym. zod sprawdza schematy w czasie wykonywania, a MCP polega na nim do generowania schematu JSON, dzięki któremu model uczy się, jak korzystać z narzędzi.

Stwórz plik .env w korzeniu projektu, który będzie zawierał ciąg łączenia.

DATABASE_URL=postgresql://your_user:your_password@localhost:5432/your_database

Niezwłocznie dodaj .env do .gitignore, ponieważ dane uwierzytelniające nigdy nie powinny być komitowane.

Skelet serwera

Następnie jest server.js, który zaczyna się od importów, nazwy i wersji serwera oraz puli bazy danych.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import pg from "pg";
import dotenv from "dotenv";

dotenv.config();
// Set up the PostgreSQL connection pool
const pool = new pg.Pool({
  connectionString: process.env.DATABASE_URL,
});
// Create the MCP server instance
const server = new McpServer({
  name: "postgres-assistant",
  version: "1.0.0",
});

Nazwa i wersja są przekazywane klientowi podczas negocjacji możliwości połączenia. Zbiór połączeń jest tworzony raz i wykorzystywany przy każdej zapytaniu, co jest znacznie bardziej efektywne niż otwieranie nowego połączenia za każdym razem.

Ujawnianie schematu

Aby model mógł tworzyć przydatne zapytania, musi wiedzieć, jakie tabele i kolumny istnieją. Aktywny schemat jest udostępniany jako czytelny zasób MCP, który może zostać włączony do kontekstu.

server.resource(
  "database-schema",
  "schema://main",
  async (uri) => {
    const result = await pool.query(`
      SELECT
        table_name,
        column_name,
        data_type
      FROM information_schema.columns
      WHERE table_schema = 'public'
      ORDER BY table_name, ordinal_position
    `);

    const schema = result.rows.reduce((acc, row) => {
      if (!acc[row.table_name]) acc[row.table_name] = [];
      acc[row.table_name].push(`${row.column_name} (${row.data_type})`);
      return acc;
    }, {});
    const schemaText = Object.entries(schema)
      .map(([table, cols]) => `${table}:\n  ${cols.join("\n  ")}`)
      .join("\n\n");
    return {
      contents: [{
        uri: uri.href,
        text: schemaText,
      }],
    };
  }
);

information_schema.columns to wbudowana widok w PostgreSQL, który opisuje każdą tabelę i kolumnę. Kod wysyła do niego zapytanie, przekształca wiersze w czytelny tekst i zwraca go jako zasób. Model odczytuje ten tekst przed podjęciem decyzji o sformułowaniu zapytania, dzięki czemu ma pełny schemat i nie musi zgadywać, jaki SQL będzie poprawny.

Narzędzie do zapytań

To jest sercem serwera – narzędzie, którego używa model do wykonywania zapytań SQL w bazie danych.

server.tool(
  "query_database",
  "Run a read-only SQL query against the PostgreSQL database. Use this to answer questions about data, counts, trends, or summaries.",
  {
    sql: z.string().describe(
      "A valid PostgreSQL SELECT query. Only SELECT statements are allowed."
    ),
  },
  async ({ sql }) => {
    // Safety gate: only allow SELECT statements
    const trimmed = sql.trim().toUpperCase();
    if (!trimmed.startsWith("SELECT")) {
      return {
        content: [{
          type: "text",
          text: "Error: only SELECT queries are permitted through this interface.",
        }],
        isError: true,
      };
    }
    try {
      const result = await pool.query(sql);
      const output = JSON.stringify(result.rows, null, 2);
      return {
        content: [{
          type: "text",
          text: `Query returned ${result.rowCount} row(s):\n\n${output}`,
        }],
      };
    } catch (err) {
      return {
        content: [{
          type: "text",
          text: `Query failed: ${err.message}`,
        }],
        isError: true,
      };
    }
  }
);

Uważnie przeczytaj ciąg opisowy, drugi argument, ponieważ model czyta go podczas decydowania o tym, czy i w jaki sposób użyć narzędzia. Napisz go jak instrukcje dla doświadczonego stażysty, który nigdy nie widział bazy danych. Schemat Zod dla parametru sql automatycznie przekształca się w schemat JSON, który widzi model i który określa strukturę argumentu. Zabezpieczenie na górze przyjmuje wyłącznie zapytania SELECT, więc żadne operacje zapisu nie mogą przejść, ani celowo, ani przez pomyłkę.

Rozpoczynanie serwera

W końcu serwer uruchamia się przy użyciu transportu stdio.

const transport = new StdioServerTransport();
await server.connect(transport);
console.error("PostgreSQL MCP server is running");

Wraz z stdio klient MCP uruchamia skrypt jako proces potomny i komunikuje się z nim za pośrednictwem standardowego wejścia i wyjścia. Jest to najprostszy i najbardziej niezawodny sposób komunikacji przy lokalnym rozwoju. Linia z logiem celowo używa console.error, aby nie zanieczyszczać kanału stdout, którego MCP używa do przesyłania wiadomości protokołowych.

Łączenie z Claude Desktop

Otwórz plik konfiguracyjny Claude Desktop. Na macOS znajduje się on tutaj:

~/Library/Application Support/Claude/claude_desktop_config.json

W systemie Windows ścieżka jest następująca:

%APPDATA%\Claude\claude_desktop_config.json

Dodaj wpis dla nowego serwera:

{
  "mcpServers": {
    "postgres-assistant": {
      "command": "node",
      "args": ["/absolute/path/to/nl-db-assistant/server.js"]
    }
  }
}

Uruchom ponownie Claude Desktop – na interfejsie pojawi się mały ikonka narzędzi, potwierdzająca, że serwery MCP są połączone i gotowe do pracy.

Próba użycia

Działają standardowe sformułowania: ile zamówień nadeszło w ciągu ostatniego tygodnia, która kategoria produktów przyniosła największe przychody w tym miesiącu, albo kim są pięciu największych klientów pod względem łącznej wartości zamówień.

Claude odczytuje aktualne zasoby schematu, tworzy odpowiedni kod SQL, wywołuje funkcję query_database, otrzymuje wyniki i przekształca je w klarowną odpowiedź. Koledzy niebędący specjalistami technicznymi nigdy nie widzą zapytania – widzą tylko pytanie i odpowiedź.

Około 80 linijek kodu JavaScript tworzy serwer, który pokazuje dowolnemu połączonemu modelowi żywy schemat PostgreSQL, przekształca pytania w języku naturalnym na zapytania SQL, zapewnia dostęp wyłącznie do odczytu oraz zwraca ustrukturyzowane dane, które model może podsumować. Został napisany tylko raz, a każdy model kompatybilny z MCP – czy to Claude obecnie, czy inny w przyszłości – może go używać bez żadnych zmian w serwerze. To właśnie jest korzyść płynąca z wspólnego protokołu.

Liczby dotyczące adopcji

Adopcja rozwija się błyskawicznie. Miesięczne liczby pobierania SDK wzrosły od 100 000 przy premierze do 97 milionów w marcu 2026 roku, co stanowi wzrost o około 970 razy w ciągu 18 miesięcy. W przeciwieństwie do tego, pakiet npm React potrzebował około trzech lat, aby osiągnąć 100 milionów miesięcznych pobierania.

W zastosowaniach produkcyjnych wykorzystywane są platformy takie jak Block, Bloomberg, Amazon oraz setki firm z listy Fortune 500. W kwietniu 2026 roku Pinterest opisał swoją produkcyjną konfigurację MCP: serwery specjalistyczne dla systemów Presto, Spark i Airflow, przy czym osoba ludzka zatwierdza operacje wrażliwe. Jak donoszono, około 66 000 wywołań narzędzi miesięcznie przez 844 aktywne użytkowniki oszczędza około 7 000 godzin pracy inżynierów miesięcznie.

Obecnie istnieją oficjalne lub utrzymywane przez społeczność serwery MCP dla Slack, GitHub, Google, Salesforce i Stripe, a także dla HubSpot, Shopify, Notion, Linear, Sentry, Figma, Webflow, Cloudflare i Postman.

Głównym tematem planu na rok 2026 jest gotowość przedsiębiorstw. Do kluczowych elementów należą logowanie przez OAuth 2.1 powiązane z usługami identyfikacji przedsiębiorstw, koordynacja między wieloma agentami, przy której jeden agent może być wywoływany jak serwer narzędzi, oraz starannie przygotowany rejestr zweryfikowanych serwerów z ocenami bezpieczeństwa.

Częste pytania

Czy MCP to po prostu wywoływanie funkcji z dodatkowymi krokami? Nie, ponieważ oba te elementy funkcjonują na różnych poziomach. Wywoływanie funkcji to działanie modelu polegające na uruchomieniu narzędzia, natomiast MCP to protokół łączący model z tym narzędziem. Wywoływanie funkcji decyduje o tym, czy uruchomić narzędzie, podczas gdy MCP zajmuje się sposobem dotarcia do niego oraz komunikacją z nim. Typowe nowoczesne rozwiązania łączą te dwa elementy.

Czy działa tylko z Claude? Wcale nie, co jest jedną z jego największych zalet. OpenAI, Google DeepMind oraz Microsoft przyjęły MCP, podobnie jak tysiące zespołów programistów. Model posiadający klient kompatybilny z MCP może korzystać z dowolnego serwera MCP, niezależnie od tego, kto stworzył każdą z tych komponentów.

Czy będzie gotowe do użycia w produkcji w 2026 roku? W większości przypadków tak, biorąc pod uwagę powyższe szerokie zastosowania. Jednak w przypadku systemów, gdzie kluczowa jest szybkość reakcji, takich jak transakcje w czasie rzeczywistym lub wymagania poniżej 100 ms, abstrakcja ma swoje koszty, a bezpośrednie połączenia API mogą być lepsze od tych za pośrednictwem MCP.

Czy jest wystarczająco bezpieczne do użycia w przedsiębiorstwach? Stopniowo się do tego zbliża. Aktualizacja specyfikacji z marca 2025 roku wprowadziła kompleksową ramę autoryzacji opartą na OAuth 2.1, a plan na 2026 rok przewiduje integrację z protokołami SAML i OIDC z dostawcami tożsamości takimi jak Okta i Azure AD. Sektorzy podlegające ścisłej regulacji, takie jak finanse czy opieka zdrowotna, nadal wymagają dodatkowych warstw zgodności na razie.

Kto nim zarządza i czy Anthropic może zmienić kierunek? Od grudnia 2025 roku protokół znajduje się w strukturach Agentic AI Foundation należącej do Linux Foundation. Dzięki temu jest to infrastruktura wspólna, neutralna pod względem dostawców i zarządzana przez społeczność, porównywalna z HTTP lub TCP/IP, a żadna pojedyncza firma nie może jednostronnie zmienić jej kierunku.

Co odróżnia narzędzie od zasobu? Narzędzie to działanie, które model decyduje się wykonać, takie jak wysłanie zapytania, przesłanie wiadomości lub utworzenie pliku. Zasób to dane, które model odczytuje pasywnie, takie jak plik, schemat lub dokument. Zasoby są ładowane do kontekstu, natomiast narzędzia są uruchamiane na żądanie podczas rozmowy.

Czy jeden serwer może obsługiwać kilka baz danych lub usług? Tak. Serwer może oferować tyle narzędzi i zasobów, ile to ma sens, a częstym rozwiązaniem jest serwer platformy danych umożliwiający dostęp odczytu do kilku baz danych, z których każda jest dostępna jako odrębne narzędzie lub zasób.

Literatura pokrewna

• Praktyczne notatki: Protokół Model Context (MCP) wyjaśniony: Przewodnik dla początkujących — Szczegółowy przewodnik po Praktycznych notatkach: Protokół Model Context (MCP) wyjaśniony: Przewodnik dla początkujących, obejmujący umowy, sprawdzania oraz miejsca na kod do wstawienia dla zespołów wdrażających ten wzorzec.
• Praktyczne notatki: Nowy MCP jest bezstanowy: Wewnątrz protokołu 2026–07–28 — Szczegółowy przewodnik po Praktycznych notatkach: Nowy MCP jest bezstanowy: Wewnątrz protokołu 2026–07–28: umowy, sprawdzania oraz miejsca na kod do wstawienia dla zespołów wdrażających ten wzorzec.