Ako postaviť MCP server a kedy to nerobiť

Ak chcete postaviť MCP server, vyberiete transport, zaregistrujete pár nástrojov s názvom, popisom a vstupnou schémou a pripojíte ho ku klientovi, napríklad ku Claude Code. Stdio je na lokálny nástroj, Streamable HTTP na vzdialený server pre viac ľudí. Kód je tá menšia časť. Ktoré nástroje ponúknete a s akými právami, rozhoduje o tom, či ich môžete agentovi dať.

MCP server je spôsob, ako sa váš systém rozpráva s AI agentmi. MCP servery od iných používame každý deň a jeden sme postavili sami: prototyp pre špedičnú firmu, ktorej systém sme postavili a prevádzkujeme. Ostal prototypom. Nižšie je, ako ho postaviť, čo by sme urobili inak a kedy ho vôbec nepotrebujete.

Čo je MCP server?

Model Context Protocol je otvorený štandard na prepojenie AI klientov s nástrojmi a dátami. Server ponúka nástroje (akcie), zdroje (dáta) a prompty. Klient, napríklad Claude Code, Claude Desktop alebo agent, ktorého si postavíte, si nástroje vypíše a zavolá ich, keď ich úloha potrebuje. Správy idú cez JSON-RPC.

Agent vašu databázu nikdy nevidí. Vidí zoznam ako tento:

• find_order: nájde jednu objednávku podľa čísla. Len na čítanie.
• draft_reply: napíše návrh odpovede, ktorý schváli človek.

Názov a popis sú vaše rozhranie. Model si nástroj vyberá podľa nich, takže pri vágnom popise sa nástroj zavolá v nesprávnej chvíli.

Stdio, alebo Streamable HTTP: lokálne, alebo vzdialene?

Špecifikácia MCP definuje dva štandardné transporty. Voľba rozhodne, kde server beží a ako sa overuje.

Autorizácia sa riadi transportom. Autorizačná špecifikácia hovorí, že implementácie so stdio „SHOULD NOT follow this specification, and instead retrieve credentials from the environment“, teda autorizačný postup nemajú používať a prihlasovacie údaje majú brať z prostredia. Vzdialený server je OAuth 2.1 resource server a musí overiť, že každý token, ktorý dostane, bol vydaný preň.

Ako postaviť MCP server krok za krokom?

Minimálny server s oficiálnym TypeScript SDK:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import { z } from 'zod'
import { getOrder } from './api.js'

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: { 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) }] }
  },
)

await server.connect(new StdioServerTransport())

Pripojenie ku Claude Code:

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

Pri stdio sa takmer každý chytí do tej istej pasce. Špecifikácia hovorí, že server „MUST NOT write anything to its stdout that is not a valid MCP message“: na stdout nesmie ísť nič okrem správ MCP. Jeden zabudnutý console.log spojenie rozbije. Logujte na stderr.

Potom testujte so skutočným klientom a skutočnou úlohou. Keď agent vyberie zlý nástroj, pozrite sa najprv na popis, až potom na kód.

Čo sme sa naučili na vlastnom MCP prototype?

Náš prototyp bol lokálny stdio server na oficiálnom SDK, založený na open-source šablóne. Mal jediný nástroj na čítanie a volal existujúce interné API systému s náhradným prihlásením. Stačilo to na to, aby sme videli agenta odpovedať zo skutočných dát. Na každodenné používanie to nestačilo.

Čo by sme urobili inak:

• Najprv API. MCP server je tenká vrstva nad API. Náš sa opieral o endpointy postavené pre obrazovky aplikácie. Najprv má byť čisté API s vlastnými pravidlami prístupu. Ako o tom uvažujeme, je v článku Pohoda API: prepojenie s vaším systémom a kto ho udrží.
• Skutočné prihlásenie od prvého dňa. Náhradné prihlásenie stačí na jedno popoludnie. Je to prvé, čo treba nahradiť, lebo rozhoduje o tom, čo agent uvidí.
• Úloha pred serverom. Server sme postavili skôr, než sme vedeli, akú úlohu s ním bude agent robiť každý deň. Správne poradie je úloha, potom nástroje, ktoré potrebuje, a až potom server.

Úprimne: vzdialený MCP server sme v produkcii zatiaľ neprevádzkovali. Všetko, čo tu píšeme o Streamable HTTP a OAuth, je zo špecifikácie, nie z našich vlastných incidentov.

Aké nástroje má agent dostať?

Začnite len s čítaním a práva pridávajte po jednom. Naše predvolené nastavenie:

Platí to isté pravidlo ako pri našich vlastných agentoch. Merge, odosielanie a nasadenie ostávajú na človeku a je to vynútené pod agentom, nie vetou v jeho prompte. Ako to funguje v Claude Code, je v článku Claude Code hooks: prečo naše hooky nerobili nič.

Kedy MCP server nestavať?

MCP server je pre situáciu, keď AI agent sám rozhoduje, ktorú akciu urobí ďalej. Veľa úloh to nikdy nepotrebuje.

Vynechajte ho, keď:

• Volá ho len váš vlastný kód. Volajte priamo svoje API.
• Úloha je pevný sled krokov. Tam obyčajná automatizácia porazí agenta.
• Čisté API ešte nemáte. Postavte najprv to.
• Nikto nevlastní model práv. Za koho môže agent konať a čo smie robiť? Bez odpovede neponúkajte žiadny zápis.

Pred spustením MCP servera

Chcete, aby váš systém pracoval s AI agentmi?

Staviame AI agentov aj to, čo pod nimi musí byť, od čistého API po MCP server navrchu, v službe AI agent pre firmu. Pre tím, ktorý chce agentov vo vlastnom vývoji, je tu AI-native SDLC pre vývojové tímy. Od roku 2023 sme dodali 15+ produkčných projektov.

Ozveme sa do dvoch pracovných dní a spolu vyberieme, čo vyriešime ako prvé.

Ak sa chcete najprv porozprávať, dohodnite si meeting na 15 minút s Filipom.

Ktorú úlohu vo vašom systéme by ste agentovi dali ako prvú?

Časté otázky

Čo je MCP server?

Program, ktorý cez Model Context Protocol ponúka AI klientovi nástroje, dáta a prompty. Agent vidí každý nástroj podľa názvu, popisu a vstupnej schémy a sám rozhodne, kedy ho zavolá. Váš systém ostáva za vaším vlastným kódom.

Stdio, alebo Streamable HTTP?

Stdio, keď server beží na tom istom počítači ako klient, napríklad lokálny nástroj pre Claude Code. Streamable HTTP, keď beží vzdialene pre viacerých používateľov. Vzdialený server potrebuje skutočnú autorizáciu.

Ako pridám MCP server do Claude Code?

Lokálny server: claude mcp add <názov> -- <príkaz>. Vzdialený: claude mcp add --transport http <názov> <url>. Servery, ktoré má dostať celý tím, patria do .mcp.json v repozitári.

Ako zabezpečím MCP server?

Lokálne čítajte prihlasovacie údaje z prostredia. Vzdialene sa držte autorizačnej špecifikácie MCP, ktorá stavia na OAuth 2.1, a overte, že každý token bol vydaný pre váš server. Ponúknite čo najmenej nástrojov, najprv len na čítanie.

Potrebuje môj produkt MCP server?

Len ak majú s vaším systémom pracovať AI agenti a sami vyberať, čo urobia. Ak ho volá len váš vlastný kód alebo sú kroky vždy rovnaké, priame volanie API alebo naplánovaná úloha je jednoduchšia a ľahšie sa testuje.