Narzędzia MCP projektowane wokół działań biznesowych, a nie endpointów

Co nie działa, gdy każdy endpoint to osobne narzędzie

Serwery wygenerowane z opisu API powstają szybko, ale model trudno z nich dobrze korzysta. Artykuł inżynierski Anthropic o narzędziach dla agentów nazywa ten wzorzec: narzędzia, które jedynie opakowują istniejące endpointy, niezależnie od tego, czy pasują do agenta, oraz nakładające się narzędzia, które odciągają go od efektywnych strategii. W praktyce koszty widać w trzech miejscach.

• Kontekst: endpointy listujące zwracają wszystko, a model czyta każdy rekord, żeby znaleźć jeden
• Kolejność: model musi się zorientować, że wyszukanie zamówienia wymaga najpierw identyfikatora klienta z innego wywołania, i czasem się myli
• Uprawnienia: każdy udostępniony endpoint model może wywołać, także te, których nikt nie zamierzał mu dawać

Zacznij od prawdziwych próśb, a nie od API

Zbierz od dwudziestu do pięćdziesięciu prawdziwych próśb od osób, które będą korzystać z asystenta: zgłoszenia, wiadomości z czatu, pytania zadawane kolegom. Pogrupuj je według działania biznesowego, które za nimi stoi. Każde działanie to kandydat na narzędzie, a dla każdego zapisujesz, kto może z niego korzystać, co czyta, co zmienia i jak wygląda poprawny wynik. Prośby, które nie pasują do żadnego działania, są powodem, żeby coś pominąć, a nie żeby dodać ogólne narzędzie do wszystkiego.

Rozpisany przykład: hipotetyczne API obsługi zamówień

Weźmy serwis zamówień z czternastoma endpointami dla klientów, zamówień, pozycji, przesyłek, śledzenia, zwrotów, refundacji i notatek. Prośby zespołu wsparcia układają się w cztery działania, więc serwer udostępnia cztery narzędzia.

• find_orders: przyjmuje e-mail klienta lub numer zamówienia i zwraca do dziesięciu zamówień ze statusem, kwotą i ostatnim zdarzeniem przesyłki
• get_order_details: jedno zamówienie z pozycjami, śledzeniem i otwartymi zwrotami, złożone z pięciu endpointów
• prepare_return: sprawdza, czy zwrot jest możliwy według zasad zwrotów, i zwraca propozycję z krótkotrwałym uchwytem potwierdzenia, niczego nie zmieniając
• confirm_return: tworzy zwrot na podstawie tego uchwytu tylko wtedy, gdy serwer zapisał zatwierdzenie użytkownika dla dokładnie tej propozycji; wywołanie bez niego albo dla zmienionej propozycji zostaje odrzucone

Refundacje, zmiany adresu i anulowanie zamówień zostają poza pierwszą wersją. Każde z nich wymaga własnych reguł i właściciela gotowego zatwierdzić narzędzie.

Co powinna obiecywać definicja narzędzia

W MCP każde narzędzie deklaruje nazwę, opis i schemat wejścia, a opcjonalnie schemat wyjścia i adnotacje. Traktuj definicję jak kontrakt, który mogą przeczytać zarówno model, jak i recenzent. Ograniczaj wejście typami, enumami i wzorcami, a nieoczekiwane pola odrzucaj. Jeśli zadeklarujesz schemat wyjścia, specyfikacja wymaga, by serwer zwracał zgodne z nim wyniki strukturalne.

{
  "name": "find_orders",
  "title": "Find orders",
  "description": "Find a customer's recent orders by email address or order number. Returns at most 10 orders, newest first.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "customer_email": { "type": "string", "format": "email" },
      "order_number": { "type": "string", "pattern": "^SO-[0-9]{8}$" },
      "status": { "type": "string", "enum": ["open", "shipped", "delivered", "returned"] }
    },
    "additionalProperties": false
  },
  "annotations": { "readOnlyHint": true, "openWorldHint": false }
}

Adnotacje opisują narzędzie klientowi jako tylko do odczytu. To wskazówki, którym klienci nie mogą ufać, gdy pochodzą z nieznanych serwerów, więc serwer i tak sam wymusza tryb tylko do odczytu i sprawdza, czy podano przynajmniej jedno pole wyszukiwania.

Błędy i kroki zapisu, które model potrafi przewidzieć

MCP rozróżnia dwa rodzaje błędów. Błędy protokołu dotyczą nieznanych narzędzi i źle zbudowanych żądań. Błędy wykonania narzędzia, zwracane w wyniku z isError ustawionym na true, dotyczą awarii API, nieprawidłowych wartości i naruszonych reguł biznesowych, a specyfikacja zaleca klientom przekazywanie ich modelowi, żeby mógł się poprawić. Pisz te komunikaty dla modelu: informacja, że zamówienie SO-12345678 dostarczono 41 dni temu, a zwroty przyjmuje się do 30 dni, pozwala mu wyjaśnić odmowę, a samo HTTP 422 już nie.

Przy zmianach oddziel przygotowanie od potwierdzenia jak w przykładzie, spraw, by wywołanie potwierdzające było idempotentne, żeby ponowienie nie utworzyło drugiego zwrotu, i powiąż każdy uchwyt z użytkownikiem, który o niego poprosił. Aktualna specyfikacja nie ma sesji na poziomie protokołu, więc stan obejmujący kilka wywołań przekazuje się jako jawny uchwyt, a serwer przy każdym wywołaniu sprawdza, czy należy on do wywołującego.

Kiedy cienka nakładka na API jest lepszym wyborem

Narzędzia oparte na działaniach biznesowych są droższe w budowie i trzeba je zmieniać razem z procesem. Cienka nakładka sprawdzi się w asystencie dla programistów, który eksploruje wewnętrzne API, w serwerze raportowym tylko do odczytu nad dobrze zaprojektowanym API zapytań albo w prototypie do wyrzucenia. Nakładanie się narzędzi waży więcej niż ich liczba: dwadzieścia wyraźnie różnych narzędzi może działać lepiej niż osiem, które niemal się dublują.

Niezależnie od wybranego kształtu zmierz go. Artykuł Anthropic zaleca ocenę narzędzi na realistycznych zadaniach i czytanie transkryptów. Zebrane prośby z oczekiwanymi wynikami wystarczą, by porównać dwa projekty, zanim użytkownicy zobaczą którykolwiek z nich.

Tworzenie serwerów MCP