Vlastní MCP server pro firemní AI nástroje

Vlastní MCP server dává AI asistentovi řízený přístup k vašim datům, API a interním akcím. Projdeme návrh nástrojů, jednoduchou implementaci v TypeScriptu, napojení na Laravel MCP vrstvu a hlavně chyby, které v produkci bolí.

Kdy má Model Context Protocol reálný přínos

MCP má smysl tam, kde nechcete do promptu kopírovat exporty, dokumentaci nebo výsledky dotazů ručně. Asistent si přes protokol vyžádá konkrétní tool, předá mu argumenty a dostane strukturovanou odpověď.

Typický případ je interní CRM, stav objednávek, znalostní báze, Jira, fakturační systém nebo analytika. Vlastní MCP server zde funguje jako bezpečná integrační vrstva, ne jako další chatovací aplikace.

Pokud řešíte jen jednorázový export dat do LLM, MCP je zbytečně těžké. Pokud ale chcete opakované volání akcí, auditovatelnost a sdílení stejné integrace mezi více klienty, protokol začne dávat ekonomický i technický smysl.

Jak navrhnout nástroje pro AI asistenta

Nezačínejte transportem. Začněte seznamem operací, které má model umět bezpečně spustit. Dobrý tool má úzký účel, jasná vstupní schémata a návratovou hodnotu, kterou model nemusí složitě parsovat z volného textu.

Místo univerzálního nástroje query_database raději napište find_customer_by_email, get_order_status nebo create_refund_draft. Model pak méně hádá a vy máte lepší kontrolu nad oprávněními i logováním.

U každé akce si napište tři pravidla: kdo ji smí volat, jestli mění data a jaký je bezpečný limit. Read-only nástroje můžete povolit dřív. Mutace, platby nebo mazání dat vždy držte za potvrzením a serverovou autorizací.

Minimální MCP server v TypeScriptu přes stdio

Nejrychlejší cesta k funkčnímu prototypu je oficiální TypeScript SDK a transport přes stdio. Ten je vhodný pro lokální asistenty typu Claude Desktop, protože server běží jako proces spuštěný klientem.

Specifikaci protokolu doporučujeme číst přímo v oficiální dokumentaci Model Context Protocol. SDK vám ušetří ruční skládání JSON-RPC zpráv, ale návrh toolů za vás neudělá.

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

const server = new McpServer({
  name: "company-crm",
  version: "1.0.0",
});

server.tool(
  "find_customer_by_email",
  {
    email: z.string().email(),
  },
  async ({ email }) => {
    const customer = await findCustomer(email);

    if (!customer) {
      return {
        content: [{ type: "text", text: "Customer not found" }],
      };
    }

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            id: customer.id,
            name: customer.name,
            plan: customer.plan,
            status: customer.status,
          }),
        },
      ],
    };
  }
);

async function findCustomer(email: string) {
  return {
    id: 42,
    name: "Acme s.r.o.",
    plan: "business",
    status: "active",
  };
}

const transport = new StdioServerTransport();
await server.connect(transport);

Ukázka je schválně malá. V produkci by findCustomer nešel přímo do databáze bez kontextu uživatele, tenant ID a oprávnění. MCP server musí být stejně přísný jako veřejné API, jen má jiného konzumenta.

Registrace serveru v klientovi a lokální ladění

Klient potřebuje vědět, jak proces spustit. U stdio transportu obvykle nastavujete příkaz, argumenty a proměnné prostředí. Nikdy nedávejte tokeny do repozitáře; používejte lokální konfiguraci nebo secret manager.

Při ladění logujte na stderr, ne na stdout. Standardní výstup používá transport pro zprávy protokolu a běžný debug výpis vám může rozbít komunikaci. To je častá chyba u prvního MCP prototypu.

{
  "mcpServers": {
    "company-crm": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "CRM_API_URL": "https://crm.example.com",
        "CRM_API_TOKEN": "use-local-secret-here"
      }
    }
  }
}

Pro TypeScript SDK sledujte i repozitář Model Context Protocol TypeScript SDK. API se vyvíjí a u produkční integrace je lepší pinovat verzi balíčku než slepě brát poslední release.

Laravel MCP: držte protokol mimo doménovou logiku

U Laravelu doporučujeme nepsat business logiku přímo do MCP handlerů. Udělejte běžné aplikační služby, policy a DTO. MCP vrstva pak jen mapuje vstupy z protokolu na volání existujícího kódu.

Balíčky označované jako Laravel MCP mohou pomoct s registrací toolů, anotacemi a transportem. Berte je ale jako adaptér. Jádro aplikace má zůstat testovatelné i bez AI klienta a bez běžícího MCP serveru.

<?php

namespace App\Mcp\Tools;

use App\Services\Orders\OrderLookup;
use Illuminate\Support\Facades\Gate;

final class GetOrderStatusTool
{
    public function __construct(
        private readonly OrderLookup $orders,
    ) {}

    public function __invoke(string $orderNumber): array
    {
        Gate::authorize('viewMcpOrderStatus');

        $order = $this->orders->findByNumber($orderNumber);

        if ($order === null) {
            return ['found' => false];
        }

        return [
            'found' => true,
            'number' => $order->number,
            'status' => $order->status,
            'paid' => $order->paid_at !== null,
            'updated_at' => $order->updated_at->toISOString(),
        ];
    }
}

Tahle třída není závislá na konkrétním MCP frameworku. Můžete ji volat z HTTP controlleru, fronty, testu i MCP adaptéru. Přesně tak má vypadat vrstva, která přežije změnu knihovny nebo klienta.

Bezpečnost MCP integrace: oprávnění, audit a limity

Největší riziko není protokol, ale příliš silný tool. Pokud modelu dáte akci run_sql nebo send_email_to_all_users, dáváte mu schopnost napáchat škodu i při dobrém úmyslu uživatele.

Každý vlastní MCP server by měl logovat název toolu, vstupní argumenty, identitu uživatele, výsledek a korelační ID. U citlivých dat logujte hash nebo zkrácenou hodnotu, ne celé osobní údaje.

Doporučujeme zavést rate limiting, allowlist nástrojů podle role a oddělené tokeny pro vývoj, staging a produkci. MCP není zkratka kolem bezpečnosti. Je to nové rozhraní k systému, takže patří do threat modelu.

Testování toolů bez závislosti na konkrétním LLM

MCP integraci netestujte jen ruční konverzací s asistentem. Model může jeden den zvolit jiný wording a vy si spletete problém v promptu s problémem v serveru. Tooly testujte deterministicky přes vstupy a očekávané výstupy.

Pro každou akci si připravte testy validace vstupů, oprávnění, chybových stavů a limitů. Užitečné jsou i kontraktační testy nad JSON schématem, aby změna názvu pole nerozbila klienty a uložené workflow.

import { describe, expect, it } from "vitest";
import { customerSchema } from "../src/schemas/customer.js";

describe("find_customer_by_email output", () => {
  it("returns a stable shape for the assistant", () => {
    const payload = {
      id: 42,
      name: "Acme s.r.o.",
      plan: "business",
      status: "active",
    };

    expect(customerSchema.parse(payload)).toEqual(payload);
  });
});

LLM je dobrý konzument, ale špatný testovací oracle. Stabilitu serveru ověřujte mimo model. Teprve potom ladíte popisy toolů, aby je asistent vybíral ve správném kontextu.

Co nasadit jako první a kde se vyplatí pomoc

Začněte read-only scénářem: vyhledání zákazníka, stav objednávky, přehled faktur nebo dotaz do znalostní báze. Teprve po auditních lozích a oprávněních přidávejte akce, které mění data.

Pokud MCP napojujete na firemní aplikaci, berte ho jako součást produktu, ne experiment bokem. Návrh oprávnění, API kontraktu a provozu můžeme spojit s AI automatizací, aby integrace vydržela i mimo první demo.

Dobře napsaný vlastní MCP server zmenší ruční práci, ale nezhorší kontrolu nad systémem. Největší výhra je v tom, že AI asistent používá stejné bezpečné služby jako zbytek aplikace a každé volání je dohledatelné.