Jak zbudować serwer MCP i kiedy tego nie robić

Aby zbudować serwer MCP, wybiera się transport, rejestruje kilka narzędzi z nazwą, opisem i schematem wejścia, a potem podłącza go do klienta, takiego jak Claude Code. stdio służy do narzędzia lokalnego, Streamable HTTP do zdalnego serwera, z którego korzysta wiele osób. Kod to mała część. To, jakie narzędzia Państwo udostępnią i z jakimi uprawnieniami, decyduje, czy można oddać je agentowi.

Serwer MCP to sposób, w jaki Państwa system rozmawia z agentami AI. Codziennie korzystamy z serwerów MCP innych, a jeden zbudowaliśmy sami: prototyp dla firmy spedycyjnej, której system zbudowaliśmy i utrzymujemy. Pozostał prototypem. Poniżej: jak go zbudować, co zrobilibyśmy inaczej i kiedy w ogóle go nie potrzeba.

Czym jest serwer MCP?

Model Context Protocol to otwarty standard łączenia klientów AI z narzędziami i danymi. Serwer udostępnia narzędzia (akcje), zasoby (dane) i prompty. Klient, na przykład Claude Code, Claude Desktop lub agent, którego Państwo zbudują, wyświetla listę narzędzi i wywołuje je, gdy zadanie tego wymaga. Wiadomości to JSON-RPC.

Agent nigdy nie widzi Państwa bazy danych. Widzi listę taką jak ta:

• find_order: wyszukuje jedno zamówienie po numerze. Tylko odczyt.
• draft_reply: pisze szkic odpowiedzi do zatwierdzenia przez człowieka.

Nazwa i opis to Państwa interfejs. Model wybiera narzędzie, czytając je, więc niejasny opis sprawia, że narzędzie zostanie wywołane w złym momencie.

stdio czy Streamable HTTP: lokalnie czy zdalnie?

Specyfikacja MCP definiuje dwa standardowe transporty. Wybór decyduje, gdzie działa serwer i jak się uwierzytelnia.

Autoryzacja zależy od transportu. Specyfikacja autoryzacji mówi, że implementacje używające stdio „SHOULD NOT follow this specification, and instead retrieve credentials from the environment”, czyli nie powinny stosować tej procedury autoryzacji, tylko pobierać dane dostępowe ze środowiska. Serwer zdalny działa jako serwer zasobów OAuth 2.1 i musi sprawdzać, czy każdy otrzymany token został wydany dla niego.

Jak zbudować serwer MCP krok po kroku?

Minimalny serwer z oficjalnym SDK TypeScript v2 (pakiet @modelcontextprotocol/server, stan na 10/2026):

import { McpServer } from '@modelcontextprotocol/server'
import { serveStdio } from '@modelcontextprotocol/server/stdio'
import * as z from 'zod/v4'
import { getOrder } from './api.js'

function createServer() {
  const server = new McpServer({ name: 'orders', version: '0.1.0' })

  server.registerTool(
    'find_order',
    {
      title: 'Find an order',
      description: 'Look up one order by its order number. Read-only.',
      inputSchema: z.object({ orderNumber: z.string() }),
    },
    async ({ orderNumber }) => {
      const order = await getOrder(orderNumber) // your API, with the caller's rights
      return { content: [{ type: 'text', text: JSON.stringify(order) }] }
    },
  )

  return server
}

void serveStdio(createServer)

Podłączenie do Claude Code:

claude mcp add orders -- node dist/server.js

Przy stdio prawie każdy wpada w jedną pułapkę. Specyfikacja mówi, że serwer „MUST NOT write anything to its stdout that is not a valid MCP message”: na stdout nie może trafić nic poza wiadomościami MCP. Zapomniany console.log zrywa połączenie. Logi proszę kierować na stderr.

Potem proszę testować z prawdziwym klientem i prawdziwym zadaniem. Gdy agent wybiera złe narzędzie, najpierw proszę sprawdzić opis, a dopiero potem kod.

Czego nauczył nas własny prototyp MCP?

Nasz prototyp był lokalnym serwerem stdio na oficjalnym SDK, zbudowanym na otwartoźródłowym szablonie startowym. Miał jedno narzędzie do odczytu i wywoływał istniejące wewnętrzne API systemu z tymczasowym logowaniem. Wystarczyło, żeby zobaczyć, jak agent odpowiada na pytania na prawdziwych danych. Nie wystarczyło, żeby ktoś używał go na co dzień.

Co zrobilibyśmy inaczej:

• Najpierw API. Serwer MCP to cienka warstwa nad API. Nasz opierał się na endpointach zbudowanych dla ekranów samej aplikacji. Najpierw powinno powstać czyste API z własnymi zasadami dostępu. Jak o tym myślimy, piszemy w API Pohoda: integracja z Państwa systemem i kto ją utrzymuje.
• Prawdziwe logowanie od pierwszego dnia. Tymczasowe logowanie wystarczy na jedno popołudnie. To pierwsza rzecz do wymiany, bo decyduje, co agent może zobaczyć.
• Zadanie przed serwerem. Zbudowaliśmy serwer, zanim wiedzieliśmy, jakie zadanie agent będzie z nim codziennie wykonywał. Właściwa kolejność to zadanie, potem potrzebne mu narzędzia, potem serwer.

Szczerze: zdalnego serwera MCP w produkcji jeszcze nie prowadziliśmy. Wszystko powyżej o Streamable HTTP i OAuth pochodzi ze specyfikacji, a nie z naszych własnych incydentów.

Jakie narzędzia powinien dostać agent?

Proszę zacząć od samego odczytu i dodawać uprawnienia po jednym. Nasz punkt wyjścia:

Obowiązuje tu ta sama zasada, którą stosujemy przy własnych agentach. Merge, wysyłka i wdrożenie zostają przy człowieku, a wymusza się to poniżej agenta, a nie zdaniem w jego prompcie. Jak to działa w Claude Code, opisujemy w Hooki Claude Code, które po cichu nic nie robią.

Kiedy nie budować serwera MCP?

Serwer MCP jest na sytuację, w której agent AI decyduje, jaką akcję podjąć jako następną. Wiele zadań nigdy tego nie potrzebuje.

Proszę odpuścić, gdy:

• Jedynym wywołującym jest Państwa własny kod. Proszę wywołać API bezpośrednio.
• Zadanie to stała sekwencja. Tam zwykła automatyzacja wygrywa z agentem.
• Nie ma jeszcze czystego API. Najpierw ono.
• Nikt nie odpowiada za model uprawnień. W czyim imieniu agent może działać i co może robić? Bez odpowiedzi proszę nie udostępniać zapisu.

Zanim uruchomią Państwo serwer MCP

Chcą Państwo, żeby system współpracował z agentami AI?

Budujemy agentów AI i to, czego potrzebują pod spodem, od czystego API po serwer MCP na wierzchu, w ramach agentów AI dla firm. Dla zespołu, który chce agentów we własnym procesie wytwarzania, jest AI-native SDLC dla zespołów deweloperskich. Od 2023 roku dostarczyliśmy ponad 15 projektów produkcyjnych.

Odezwiemy się w ciągu dwóch dni roboczych z kilkoma pytaniami o Państwa pracę. Potem ustalimy, co zrobimy najpierw.

Jeśli wolą Państwo najpierw porozmawiać, proszę zarezerwować 15-minutową rozmowę wstępną.

Które zadanie w Państwa systemie oddaliby Państwo agentowi jako pierwsze?

Najczęstsze pytania

Czym jest serwer MCP?

Programem, który udostępnia klientowi AI narzędzia, dane i prompty przez Model Context Protocol. Agent widzi każde narzędzie po nazwie, opisie i schemacie wejścia i sam decyduje, kiedy je wywołać. Państwa system pozostaje za Państwa własnym kodem.

stdio czy Streamable HTTP?

stdio, gdy serwer działa na tej samej maszynie co klient, na przykład lokalne narzędzie dla Claude Code. Streamable HTTP, gdy działa zdalnie dla wielu użytkowników. Serwer zdalny potrzebuje prawdziwej autoryzacji.

Jak dodać serwer MCP do Claude Code?

Serwer lokalny: claude mcp add <nazwa> -- <polecenie>. Zdalny: claude mcp add --transport http <nazwa> <url>. Serwery, które ma dostać cały zespół, trafiają do .mcp.json w repozytorium.

Jak zabezpieczyć serwer MCP?

Lokalnie dane dostępowe proszę czytać ze środowiska. Zdalnie proszę stosować specyfikację autoryzacji MCP opartą na OAuth 2.1 i sprawdzać, czy każdy token został wydany dla Państwa serwera. Proszę udostępniać jak najmniej narzędzi, najpierw tylko do odczytu.

Czy potrzebuję serwera MCP dla mojego produktu?

Tylko jeśli agenci AI mają pracować z Państwa systemem i sami wybierać, co robić. Jeśli jedynym wywołującym jest Państwa własny kod albo kroki są zawsze takie same, bezpośrednie wywołanie API lub zadanie harmonogramu jest prostsze i łatwiejsze do testowania.