MCP eszköztervezés: tanulságok egy 20 eszközes Jira szerverről

Az MCP eszköztervezés az a munka, amellyel eldöntjük, milyen eszközteket tesz egy Model Context Protocol szerver elérhetővé, és hogyan nevezzük el, írjuk le, paraméterezzük és válaszolunk mindegyikre úgy, hogy az ügynök az első próbálkozásra a megfelelő eszközt válassza, és ehhez a lehető legkevesebb tokent használja el. A protokoll csak az eszközhívásokat szállítja. Hogy az ügynöknek sikerül-e, szinte teljes egészében attól függ, milyen eszközfelületet adsz neki.

Írtam egy Jira MCP szervert 20 eszközzel: jegyek keresése, létrehozása, módosítása és léptetése, kommentek, csatolmányok, epicek, valamint tesztesetek és tesztfutások. A Jira jó teszteset, mert a REST API-ja széles, az adatai pedig zajosak. Ez a bejegyzés összegyűjti a legfontosabb tervezési szabályokat, alátámasztva az Anthropictól és másoktól publikált mérésekkel: mit érnek az eszközdefiníciók, mikor érdemes összevonni az eszközöket, hogyan nevezzük el őket, mit adjunk vissza, hogyan jelentsük a hibákat, és hogyan ellenőrizzük az eredményt egy kis evalval.

Mennyi tokent érnek az MCP eszközdefiníciók?

Minden eszközdefiníció betöltődik a modell kontextusába, mielőtt az ügynök elolvassa a promptodat, egy nagy szerver tehát minden fordulóban több ezer tokent fizet. A mért értékek egy szlájn 15 eszközből álló szerver esetén nagyjából 3 000 token, egy több szerverből álló nagy felállás esetén több mint 100 000 token.

A Blocks.ai a Claude Sonnet 4 token számlálójával mérte a séma költségét, úgy, hogy egy kérést összehasonlított az eszközök csatolásával és anélkül: egy 15 eszközből álló szerver 3 185 tokent vitt, a GitHub MCP szerver mind a 85 bekapcsolt eszközzel 26 644-et. Az Anthropic advanced tool use bejegyzése (2025. november 24.) ötszerveres felállást ír le (GitHub, Slack, Sentry, Grafana, Splunk) körülbelül 55 000 tokennel, és nagy léptékben, optimalizálás előtt 134 000 tokenre emelkedő eszközdefiníciókat.

Ha elosztod a két Blocks.ai számot, a szlájn szervernél körülbelül 210 token jut egy eszközre, a GitHubnál körülbelül 310. Az egy eszközre jutó költség nem az igazi emelő. A darabszám az. Húsz eszköz reális méret egy egész Jira-szerű termékhez; nyolcvanöt akkor lesz, ha minden végpontból eszköz válik.

Vissza kell tükrözniük az MCP eszközöknek a REST API-t egy az egyben?

Nem. Az, hogy minden REST végpontból eszköz lesz, a leggyakoribb MCP tervezési hiba: megszorozza a definíciókat, és az ügynököt arra kényszeríti, hogy alacsony szintű hívásokat fűzzön össze. Az ügynök által elvégzett feladatok köré építsd az eszközöket, és vonj össze olyan végpontokat, amelyeket mindig együtt használnak.

Az Anthropic Writing effective tools for agents cikke (2025. szeptember 11.) a kanonikus példákat adja: list_users, list_events és create_event helyett építs schedule_event-et; read_logs helyett search_logs-ot, amely csak a releváns sorokat adja vissza; get_customer_by_id, list_transactions és list_notes pedig legyen get_customer_context. Egy összevont eszköz több API hívást is végrehajthat a felszín alatt.

Egy Jira-szerű tracker esetén a teszt konkrét. Ha egy ügynök kommentel egy jegyhez, mindig előbb lehívja a jegyet? Ha mozgat egy jegyet, tudnia kell, mely átmenetek engedélyezettek? Ahol a válasz „mindig”, ott a második hívás jelölt arra, hogy belefoglaljuk az első eszköz eredményébe. Ahol a válasz „csak néha”, ott maradjon külön a két eszköz.

A mellékhatás ág ugyanúgy biztonsági, mint pontossági kérdés. Egy csak olvasható keresés és egy olyan írás, ami megváltoztatja egy jegy státuszát, külön eszköz maradjon, hogy a host az egyiket automatikusan jóváhagyhassa, a másikról meg emberrel kérdezzön. Ez ugyanaz a határ, amelyet máshol az ügynökskilljeim betartatnak: az ember hagy jóvá mindent, ami nyilvános vagy visszafordíthatatlan.

Hogyan nevezzük el és írjuk le az MCP eszközöket?

Nevezz el minden eszközt egy igével és egy olyan néptérrel, amelyet az ügynök nem keverhet össze egy másik szerver eszközeivel, és írd meg minden leírását úgy, mintha egy új kollégát vezetnél be: mit csinál az eszköz, mikor használd, mit jelentenek a paraméterek, és mi jön vissza.

Az MCP tools spec 1 és 128 karakter közti neveket kér, betűkből, számjegyekből, aláhúzásból, kötőjelezből és pontból, egy szerveren belül egyediekkel. A szervereken átívelő egyediség nem garantált: két szerver is kínálhat search-öt, és a kliensekre hárul, hogy ezt feloldják, például egy szerverazonosító előprefixezésével. Ne támaszkodj arra, hogy a kliensek ezt jól megoldják. Az Anthropic szerint a prefix- vagy suffixalapú néptérválasztás (jira_search vs. search_jira) „nem triviális hatással” volt az eszközhasználati értékeléseikre, válassz tehát egyet, és teszteld.

A leírások viszik a kiválasztási jel legnagyobb részét. Az Anthropic írja, hogy „még a leírások apró finomítása is drámai javulást hozhat”. A gyakorlatban ez ezt jelenti:

• Mondd meg, mit ad vissza az eszköz, nem csak azt, hogy mit csinál. Az ügynök a következő hívást a várható kimenet alapján választja.
• Nevezd meg a lekérdezési nyelvet vagy formátumot, ha van. Egy JQL-t fogadó keresőeszköz ezt mondja el, és mutass egy példát.
• Egyértelmű paraméterneveket használj: issue_key id helyett, user_email user helyett.
• A korlátok kerüljenek a leírásba: oldalméret, maximális eredményszám, mely mezők szerkeszthetők.

// Illustrative tool definition (not copied from a real server)
{
  "name": "jira_search_issues",
  "description": "Search Jira issues with a JQL query, e.g. project = PROJ AND status = \"In Progress\". Returns up to `limit` issues with key, summary, status and assignee name. Use response_format \"detailed\" only when you need descriptions or custom fields.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "jql": { "type": "string", "description": "JQL query" },
      "limit": { "type": "integer", "description": "Max issues, default 20" },
      "response_format": { "type": "string", "enum": ["concise", "detailed"] }
    },
    "required": ["jql"]
  }
}

Mit adjon vissza egy MCP eszköz?

A legkisebb eredményt add vissza, amivel az ügynök megteheti a következő lépést: olvasható mezők belső ID-k helyett, alapértelmezés szerint tömör formátum, és nagy eredménynél lapozás vagy levágás, kísérő útmutatással.

Az Anthropic eszközírási útmutatója megállapította, hogy az átlátszatlan alfanumerikus UUID-k feloldása érthető nyelvre „jelentősen javítja Claude pontosságát”, és hogy az olyan mezők, mint a name és a file_type, sokkal gyakrabban tájékoztatják a következő lépésről, mint a nyers azonosítók. A ResponseFormat példája megmutatja a méretkülönbséget: ugyanaz a Slack-szál 206 tokenbe került a részletes, ID-ket tartalmazó formátumban, és 72-be a tömörbe, nagyjából egyharmadába. Ha mindkettőt felkínálod, tömörrel alapértelmezés szerint, az ügynök csak akkor kérhet ID-kat, ha egy követő híváshoz kell belőlük.

A méretkorlátok nem elméletiek. A Claude Code alapértelmezés szerint 25 000 tokenre korlátozza az eszközválaszokat, ugyanabban az útmutatóban. Egy tracker keresés, amely a teljes leírásokat, a komment-szálakat és minden egyéni mezőt visszaadja, egy forgalmas projekten belütközik ebbe a korlátba. Lapozd az eredményeket, válassz értelmes alapértékeket, és ha levágsz, írd le az eredményben, és mondd el az ügynöknek, hogyan juthat a többihez (szűkebb lekérdezés, következő oldal, vagy a részletes formátum egy jegyhez).

Hogyan jelentsék az MCP eszközök a hibákat?

A helyreállítható problémákat eszközhívási hibaként jelentésd isError: true értékkel, és olyan üzenettel, amely megmondja, mi volt a baj, és hogyan néz ki egy érvényes hívás. A modell így maga javítja ki a hívását, ahelyett, hogy feladná vagy vakon újrapróbálkozna.

Az MCP spec kétféle hibát különböztet meg. A protokollhibák (ismeretlen eszköz, hibás kérés) JSON-RPC hibák, amelyekből a modellek ritkábban állnak talpra. Az eszközhívási hibák, például a bemenet validálása vagy az üzleti logika hibája, az eszköz eredményébe kerülnek, és a klienseknek át kell adniuk őket a modellnek, hogy az maga javíthasson. Az Anthropic útmutatója ugyanezt mondja a másik oldalról: az átlátszatlan hibakódok és a stack trace-ek nem segítenek; a konkrét, tevékeny üzenetek egy helyes bemenet példájával igen.

A Jira itt egyértelmű leckét adott. Az API-ja egyes mezőkben a wiki-jelölést egy puszta HTTP 400-zal, magyarázat nélkül utasítja el. Az ügynök, aki csak a „400 Bad Request”-et látja, találgatni fog, gyakran úgy, hogy újraküldi ugyanazt a payloadot. A javítás két részből állt: küldd a tartalmat ADF-ben (Atlassian Document Format), és írás után ellenőrizd az eredményt úgy, hogy rákérdezel rá, nehogy a válaszban bízd meg. Az általános szabály a saját szerveredre: fordítsd le az upstream hibákat olyan mondatokká, amelyekkel az ügynök tud dolgozni.

// Illustrative tool execution error
{
  "content": [{ "type": "text", "text": "Transition 'Done' is not available for PROJ-42 in status 'Open'. Allowed transitions: 'Start progress', 'Close'. Call again with one of these names." }],
  "isError": true
}

Mikor nem elég egy kisebb eszközlista? Tool search, kódvégrehajtás és trade-off-ok

Ha egy ügynöknek több száz eszközhöz kell hozzáférnie, az összevonás önmagában nem tartja kicsin a kontextust. A késleltetett betöltés (tool search) és a kódvégrehajtás helyette igény szerinti tölti be a definíciókat, egy extra lépés és több mozgó alkatrész árán.

Az Anthropic Tool Search Tool defer_loading: true jelöléssel jelöli az eszközöket, így azok kereséssel találhatók meg, nem előre betöltve. Saját méréseikben ez 85%-kal csökkentette a tokenhasználatot, és az Opus 4 pontosságát 49%-ról 74%-re, az Opus 4.5 esetén 79,5%-ról 88,1%-re emelte. Az eszközhasználati példák hozzáadása a definíciókhoz 72%-ról 90%-re javította a pontosságot összetett paramétereknél. A code execution with MCP bejegyzésük (2025. november 4.) továbbmegy: ha az eszközöket egy fájlrendszeren kódként mutatják be, egy munkafolyamat 150 000 tokenről 2 000-re csökkent, 98,7%-os megtakarítás.

A trade-off-ok valósak. Az összevont eszközök elrejtik a lépéseket, ezért egy három dolgot tevő munkafolyamat-eszköz mindegyikhez világos hibaküldetést igényel. A tool search plusz egy kört ad, és ha a leírások homályosak, elmisselheti a megfelelő eszközt. A kódvégrehajtáshoz sandbox kell, ami önmagában egy biztonsági projekt (lásd kódoló ügynökök sandboxolása). És néha egyáltalán nem az MCP a helyes válasz: egy CLI plusz egy skillfájl olcsóbb lehet helyi munkához. Az AGENTS.md, skillek, MCP vagy CLI cikkben hasonlítom össze ezeket a lehetőségeket.

Hogyan mérjük az eszközválasztást: egy kis eval és egy checklist

Hogy az ügynökök helyesen választanak-e eszközt, úgy derül ki, ha futtatsz valós feladatokat, és megnézed, mely eszközöket hívták, milyen argumentumokkal, és hogy sikerült-e a feladat. Az Anthropic ügynök eval útmutatója azt javasolja, hogy 20 és 50 közötti feladattal indulj, valódi hibákból merítve.

Az Anthropic olyan értékelési feladatokat javasol, amelyek valós munkafolyamatokon alapulnak és több eszközhívást igényelnek, mindegyikhez egy ellenőrizhető eredménnyel és opcionálisan a várható eszközhívásokkal. Egy tracker szerver esetén egy feladat lehet: „vidd át az aktuális sprintben nekem kiosztott összes nyitott hibát In Review állapotba, és tegyél mellé kommentet a PR linkjével”. Rögzítsd a transzkriptumot, és nézz meg három dolgot: a kiválasztott eszközöket, a hívások számát és a végállapotot a trackerben. Módosíts egy leírást, futtasd újra, és hasonlítsd össze. Többet az LLM funkciók evaljaiban.

1. Számold meg az eszközeidet, és mérd a tokenköltségüket a modelled token számlálójával, a szerverrel és anélkül.
2. Vond össze azokat a műveleteket, amelyeket mindig együtt hívnak; tartsd külön az olvasást és az írást.
3. Adj néptérteret minden eszköznévhez, és tartsd az egész szerveren egy konvenciót (prefix vagy suffix).
4. Írj leírásokat, amelyek kimondják a kimenetet, a lekérdezési formátumot, a korlátokat és egy példát.
5. Adj vissza neveket, nem UUID-kat, tömör alapértékkel és részletes opcióval.
6. Lapozz és vágj kísérő útmutatással, jól a kliens válaszkorlátja alatt.
7. Fordítsd le az upstream hibákat tevékeny isError eredményekké, és ellenőrizd az írásokat visszaolvasással.
8. Tartsd a tools/list-et stabil sorrendben, ahogyan a 2026-07-28 spec mostantól ajánlja, hogy a kliensek cache-e érvényes maradjon.
9. Futtass egy kis eszközválasztási evalt minden leírásmódosítás után.

A protokolloldal is mozgásban van; az MCP 2026-07-28 migrációs útmutató foglalkozik azzal, hogyan kerülnek a handle-ök és a megerősítések az eszközök sémáiba, az MCP szerver biztonsági checklist pedig azzal, mi mehet el, ha maguk az eszközleírások rosszindulatúak. Ha saját termékhez tervezel MCP szervert, épp ilyen munkát csinálok AI mérnökként.

Források

1. Writing effective tools for agents – with agents – Anthropic, 2025. szeptember 11.
2. Introducing advanced tool use on the Claude Developer Platform – Anthropic, 2025. november 24.
3. Code execution with MCP – Anthropic, 2025. november 4.
4. MCP vs CLI: context window cost – Blocks.ai
5. Demystifying evals for AI agents – Anthropic, 2026. január 9.
6. MCP 2026-07-28 specification: Tools