Jak postavit MCP server a kdy to nedělat

Když chcete postavit MCP server, vyberete transport, zaregistrujete pár nástrojů s názvem, popisem a vstupním schématem a připojíte ho ke klientovi, třeba ke Claude Code. Stdio je na lokální nástroj, Streamable HTTP na vzdálený server pro víc lidí. Kód je ta menší část. Které nástroje nabídnete a s jakými právy, rozhoduje o tom, jestli je můžete agentovi dát.

MCP server je způsob, jak váš systém mluví s AI agenty. MCP servery od jiných používáme každý den a jeden jsme postavili sami: prototyp pro speditérskou firmu, jejíž systém jsme postavili a provozujeme. Zůstal prototypem. Níže je, jak ho postavit, co bychom udělali jinak a kdy ho vůbec nepotřebujete.

Co je MCP server?

Model Context Protocol je otevřený standard pro propojení AI klientů s nástroji a daty. Server nabízí nástroje (akce), zdroje (data) a prompty. Klient, třeba Claude Code, Claude Desktop nebo agent, kterého si postavíte, si nástroje vypíše a zavolá je, když je úloha potřebuje. Zprávy jdou přes JSON-RPC.

Agent vaši databázi nikdy nevidí. Vidí seznam jako tento:

• find_order: najde jednu objednávku podle čísla. Jen na čtení.
• draft_reply: napíše návrh odpovědi, který schválí člověk.

Název a popis jsou vaše rozhraní. Model si nástroj vybírá podle nich, takže u vágního popisu se nástroj zavolá v nesprávnou chvíli.

Stdio, nebo Streamable HTTP: lokálně, nebo vzdáleně?

Specifikace MCP definuje dva standardní transporty. Volba rozhodne, kde server běží a jak se ověřuje.

Autorizace se řídí transportem. Autorizační specifikace říká, že implementace se stdio „SHOULD NOT follow this specification, and instead retrieve credentials from the environment“, tedy autorizační postup používat nemají a přihlašovací údaje mají brát z prostředí. Vzdálený server je OAuth 2.1 resource server a musí ověřit, že každý token, který dostane, byl vydaný pro něj.

Jak postavit MCP server krok za krokem?

Minimální server s oficiálním 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())

Připojení ke Claude Code:

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

U stdio se skoro každý chytí do jedné pasti. Specifikace říká, že server „MUST NOT write anything to its stdout that is not a valid MCP message“: na stdout nesmí jít nic kromě zpráv MCP. Jeden zapomenutý console.log spojení rozbije. Logujte na stderr.

Pak testujte se skutečným klientem a skutečnou úlohou. Když agent vybere špatný nástroj, podívejte se nejdřív na popis, až potom na kód.

Co jsme se naučili na vlastním MCP prototypu?

Náš prototyp byl lokální stdio server na oficiálním SDK, založený na open-source šabloně. Měl jediný nástroj na čtení a volal existující interní API systému s náhradním přihlášením. Stačilo to na to, abychom viděli agenta odpovídat ze skutečných dat. Na každodenní používání to nestačilo.

Co bychom udělali jinak:

• Nejdřív API. MCP server je tenká vrstva nad API. Náš se opíral o endpointy postavené pro obrazovky aplikace. Nejdřív má být čisté API s vlastními pravidly přístupu. Jak o tom přemýšlíme, je v článku Pohoda API: napojení na váš systém a kdo ho udržuje.
• Skutečné přihlášení od prvního dne. Náhradní přihlášení stačí na jedno odpoledne. Je to první, co je potřeba nahradit, protože rozhoduje o tom, co agent uvidí.
• Úloha před serverem. Server jsme postavili dřív, než jsme věděli, jakou úlohu s ním bude agent dělat každý den. Správné pořadí je úloha, pak nástroje, které potřebuje, a teprve potom server.

Upřímně: vzdálený MCP server jsme v produkci zatím neprovozovali. Všechno, co tu píšeme o Streamable HTTP a OAuth, je ze specifikace, ne z našich vlastních incidentů.

Jaké nástroje má agent dostat?

Začněte jen se čtením a práva přidávejte po jednom. Naše výchozí nastavení:

Platí stejné pravidlo jako u našich vlastních agentů. Merge, odesílání a nasazení zůstávají na člověku a je to vynucené pod agentem, ne větou v jeho promptu. Jak to funguje v Claude Code, je v článku Claude Code hooks: proč naše hooky nedělaly nic.

Kdy MCP server nestavět?

MCP server je pro situaci, kdy AI agent sám rozhoduje, kterou akci udělá dál. Spousta úloh to nikdy nepotřebuje.

Vynechte ho, když:

• Volá ho jen váš vlastní kód. Volejte přímo své API.
• Úloha je pevný sled kroků. Tam obyčejná automatizace porazí agenta.
• Čisté API ještě nemáte. Postavte nejdřív to.
• Nikdo nevlastní model práv. Za koho smí agent jednat a co smí dělat? Bez odpovědi nenabízejte žádný zápis.

Před spuštěním MCP serveru

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

Stavíme AI agenty i to, co pod nimi musí být, od čistého API po MCP server navrchu, v rámci služby AI agent pro firmu. Pro tým, který chce agenty ve vlastním vývoji, je tu AI-native SDLC pro vývojové týmy. Od roku 2023 jsme dodali 15+ produkčních projektů.

Ozveme se do dvou pracovních dnů a společně vybereme, co vyřešíme jako první.

Pokud si chcete nejdřív promluvit, domluvte si meeting na 15 minut s Filipem.

Kterou úlohu ve vašem systému byste agentovi dali jako první?

Časté otázky

Co je MCP server?

Program, který přes Model Context Protocol nabízí AI klientovi nástroje, data a prompty. Agent vidí každý nástroj podle názvu, popisu a vstupního schématu a sám rozhodne, kdy ho zavolá. Váš systém zůstává za vaším vlastním kódem.

Stdio, nebo Streamable HTTP?

Stdio, když server běží na stejném počítači jako klient, třeba lokální nástroj pro Claude Code. Streamable HTTP, když běží vzdáleně pro víc uživatelů. Vzdálený server potřebuje skutečnou autorizaci.

Jak přidám MCP server do Claude Code?

Lokální server: claude mcp add <název> -- <příkaz>. Vzdálený: claude mcp add --transport http <název> <url>. Servery, které má dostat celý tým, patří do .mcp.json v repozitáři.

Jak zabezpečím MCP server?

Lokálně čtěte přihlašovací údaje z prostředí. Vzdáleně se držte autorizační specifikace MCP, která staví na OAuth 2.1, a ověřte, že každý token byl vydaný pro váš server. Nabídněte co nejméně nástrojů, nejdřív jen na čtení.

Potřebuje můj produkt MCP server?

Jen pokud mají s vaším systémem pracovat AI agenti a sami vybírat, co udělají. Když ho volá jen váš vlastní kód nebo jsou kroky vždy stejné, přímé volání API nebo naplánovaná úloha je jednodušší a líp se testuje.