MCP-integráció

14.1   Mikor válaszd az AbstractMcpTool-t?

Ha egy külső vagy belső rendszer (hibajegy-kezelő, monitorozó rendszer, dokumentumtár, nyilvántartás) MCP szervert kínál, az AbstractMcpTool a legrövidebb út az adataihoz: a plugin csak megnevezi a szervert, és a tool logikájában a szerver tool-jait hívja. A kapcsolat felépítése, a protokoll-verzió egyeztetése, a hitelesítés, az időkorlátok, az elérhetőség figyelése, a hívások auditja és a külső tartalom biztonságos kontextusba helyezése a platform dolga.

Az MCP tool-ok kiválasztása és sorrendje a plugin kódjában marad: a platform LLM-je nem választ a szerver tool-jai közül. A tool maga pontosan úgy aktiválódik, mint bármely más tool – a getExecutableInstruction() és a kérés domain-je, system-szűrője alapján –, és a futása során a plugin kódja dönti el, melyik MCP tool-t, milyen argumentumokkal, milyen sorrendben hívja.

A platform a 2025-03-26 és 2025-11-25 közötti, munkamenet-alapú, és a 2026-07-28-as, állapotmentes MCP protokollverziót is beszéli Streamable HTTP-n; hogy egy szerver melyiket használja, azt a platform maga állapítja meg. A plugin kódja mindkét esetben ugyanaz.

14.2   Az alaposztály – AbstractMcpTool<Request>

A Request típusparaméter a felhasználói kérésből kinyert paraméterek beanje, pontosan úgy, mint bármely más tool-nál (→ 3. fejezet). A szokásos tool-metódusokon (getName(), getDomain(), getEligibleSystem(), getPriority(), getInstruction(), getExecutableInstruction(), getRequestClass(), getIdentityDescription()) túl az alábbiak tartoznak az alaposztályhoz.

Az alaposztály isEligible() metódusa akkor ad true-t, ha a tool egyik deklarált szervere sem ismerten elérhetetlen. Ha a leszármazott saját jogosultsági feltételt ad hozzá, az ősosztály döntését is figyelembe kell vennie (super.isEligible(userData) && ...).

A futás kontextusát az McpExecutionContext rekord hordozza: a kérés domain-je, system-szűrője, szövege, nyelve és kulcsszavai, a kérés azonosítója, és ha ismert, a chat és a bejelentkezett felhasználó azonosítója.

14.3   Szerverek deklarálása – McpServerDescriptor

Egy szervert egy McpServerDescriptor ír le: hol érhető el, hogyan kell hitelesíteni, milyen időkorlátokkal hívható, és a platform infrastruktúráján belül vagy azon kívül fut-e. A leíró azonosítója egy tool-on belüli alias – a hívások erre hivatkoznak. A leíró megváltoztathatatlan; a módosító metódusok új példányt adnak.

Az ajánlott forma a konfigurációból való beolvasás (McpServerDescriptor.fromEnvironment(id, environment)): a plugin saját plugin.properties fájljában adja meg a kulcsokat, a titkokat környezeti változóból feloldva, így a szerver címe és tokenje telepítésenként, újrafordítás nélkül állítható (→ 11. fejezet).

# plugin.properties
mcp.kk-grafana.url=${GRAFANA_MCP_URL:}
mcp.kk-grafana.external=false
mcp.kk-grafana.headers.Authorization=Bearer ${GRAFANA_MCP_TOKEN:}
mcp.kk-grafana.timeout.connect-ms=5000
mcp.kk-grafana.timeout.call-ms=60000

Bevett minta, hogy üres URL esetén a tool nem deklarál szervert – így egy nem konfigurált telepítésben a tool egyszerűen nem aktiválható, és nem okoz hibát:

@Autowired
private Environment environment;

@Override
public List<McpServerDescriptor> getMcpServers() {
    String url = environment.getProperty("mcp." + SERVER + ".url");
    if (url == null || url.isBlank()) {
        return List.of();
    }
    return List.of(McpServerDescriptor.fromEnvironment(SERVER, environment)
        .expectTools("search_dashboards", "list_datasources", "query_prometheus"));
}

Az expectTools(...) a szerveren elvárt tool-neveket adja meg: ha közülük bármelyik hiányzik a szerver tool-listájából, a szerver állapota leromlottnak minősül, és figyelmeztetés kerül a naplóba – így egy szerver-frissítés okozta eltérés még az első sikertelen hívás előtt kiderül. Az expectTool(name, argumentsBean) ezen felül a hívás argumentum-beanjét is összeveti a tool távoli bemeneti sémájával: ha a séma olyan kötelező mezőt ír elő, ami a beanből hiányzik, vagy a bean olyan mezőt küldene, amit a séma nem ismer, a szerver szintén leromlottnak minősül.

Konfiguráció helyett a leíró kódból is felépíthető: McpServerDescriptor.builder(id, url), majd external(...), header(...) / headers(...), connectTimeoutMs(...), callTimeoutMs(...), insecureTls(...), oauth(...), elicitation(...), expectTool(...) és build().

14.4   Hívások – IMcpSession

Az executeMcp() egy IMcpSession példányt kap, amely egyetlen tool-futás élettartamára szól. Ezen keresztül a tool tetszőleges számú, akár egymásra épülő hívást indíthat – egy hívás eredménye a következő hívás argumentuma lehet. A példány nem szálbiztos: egy futáson belül, egy szálról használandó.

McpCallOptions – a hívás beállításai

A platform magától csak akkor ismétel egy hívást, ha a kérés bizonyíthatóan el sem jutott a szerverhez. A szerver readOnlyHint jelzésére ez a döntés nem épül: hogy egy hívás ismételhető-e, azt a plugin mondja meg.

McpToolResult – az eredmény

GrafanaDatasourceList list = mcp.callTool(SERVER, "list_datasources",
        Map.of("type", "prometheus"), McpCallOptions.retryable())
    .as(GrafanaDatasourceList.class);

McpToolResult value = mcp.callTool(SERVER, "query_prometheus",
        Map.of("datasourceUid", uid, "expr", request.getPromQl(),
               "endTime", "now", "queryType", "instant"),
        McpCallOptions.retryable());

Hibák – McpException

A protokoll-, átviteli és megszakítási hibák McpException-ként érkeznek; a getKind() megmondja, mi történt, és ebből az is következik, hogy a hívás elérte-e a szervert. Ha a futás hibára fut, a tool eredmény nélkül zárul.

14.5   Kérdezés a hívás előtt

Gyakori helyzet, hogy egy MCP tool kötelező paramétere a kérésből nem derül ki, de a plugin fejlesztője tudja, honnan szerezhető be: egy másik MCP-hívás adja meg a lehetséges értékeket. Ha csak egy lehetséges érték van, az a paraméter; ha több, a felhasználónak kell választania – még mielőtt a cél-tool hívása elmenne. Erre az IMcpSession négy metódust ad.

Hogyan jelenik meg a kérdés?

A kérdés a tisztázó körben, a tool nevében jelenik meg. Egyetlen választós vagy igen–nem mezőnél gombok, egyetlen szöveges vagy szám mezőnél szabad szöveges bevitel jelenik meg, és a beírt érték változatlanul kerül a paraméterbe. Több hiányzó mezőnél a felhasználó szabad szövegben válaszol, az értékeket a platform helyi modellje tölti ki, és a kitöltött adatok még egyszer, jóváhagyásra vagy javításra megjelennek. A típusnak, az értéklistának, a hosszúsági és értékkorlátoknak vagy a formátumnak (e-mail, webcím, dátum, időpont) nem megfelelő érték nem kerül be: a kérdés az ok megjelölésével megismétlődik. Minden kérdésnél van „Kihagyom” lehetőség – ekkor a metódus null-t ad.

A válasz után: a futás elölről indul

Kérdésnél a futás megszakad (→ 14.4), és a tool-futás a kérdéssel zárul. A válasz után a tool-futás elölről indul, ugyanazzal a kinyert kérés-paraméterrel, és amikor a kód ugyanazzal a kulccsal újra eljut ugyanahhoz a kérdéshez, a metódus már a választ adja vissza. Ebből három szabály következik:

• A kulcs legyen stabil – egy adott kérdéshez a futáson belül mindig ugyanaz a key tartozzon. A completeArguments kulcsa maga a szerver, a tool és az átadott argumentumok; neki nincs kulcs-paramétere.
• A kód a kérdésig legyen determinisztikus – az újrafutásban ugyanazokkal a döntésekkel kell ugyanoda eljutnia.
• A kérdés előtti hívások újra lefutnak – a kérdést megelőző MCP-hívások (pl. a lehetséges értékek listája) az újrafutásban ismét elmennek. Kérdés előtt ezért lehetőleg csak olvasó hívás legyen.

Ha a choose újrafutásában a korábban választott érték már nincs a lehetőségek között (pl. időközben törölték), a kérdés újra megjelenik. Egy kérdésre legfeljebb öt kör lehet; utána a futás UNSUPPORTED_RESULT hibával zárul.

Példa – választás több adatforrás közül

A metrika-lekérdezéshez adatforrás-azonosító kell. Ha a felhasználó megnevezte az adatforrást, a névre illeszkedők, egyébként az összes Prometheus adatforrás a jelölt; egyetlen jelöltnél nincs kérdés:

private String prometheusUid(IMcpSession mcp, String requested) {
    GrafanaDatasourceList list = mcp.callTool(SERVER, "list_datasources",
            Map.of("type", "prometheus"), McpCallOptions.retryable())
        .as(GrafanaDatasourceList.class);
    if (list == null || list.getDatasources() == null || list.getDatasources().isEmpty()) {
        return null;
    }
    List<GrafanaDatasourceList.Datasource> candidates = list.getDatasources();
    if (requested != null && !requested.isBlank()) {
        String wanted = requested.trim().toLowerCase(Locale.ROOT);
        List<GrafanaDatasourceList.Datasource> matching = candidates.stream()
            .filter(d -> wanted.equals(d.getUid())
                || (d.getName() != null && d.getName().toLowerCase(Locale.ROOT).contains(wanted)))
            .toList();
        if (!matching.isEmpty()) {
            candidates = matching;
        }
    }
    List<McpChoice> choices = candidates.stream()
        .map(d -> McpChoice.of(d.getUid(), d.getName()
            + (Boolean.TRUE.equals(d.getIsDefault()) ? " (alapértelmezett)" : "")))
        .toList();
    return mcp.choose("prometheus-datasource",
        "Melyik Prometheus adatforrásból kérdezzem le a metrikát?", choices);
}

Példa – hiányzó kötelező paraméterek bekérése

Map<String, Object> args = new LinkedHashMap<>();
args.put("project", request.getProject());   // lehet null
args.put("summary", request.getSummary());
args = mcp.completeArguments(SERVER, "create_issue", args,
        "A hibajegy létrehozásához még szükség van néhány adatra.");
if (args == null) {
    return null;                              // a felhasználó kihagyta
}
McpToolResult created = mcp.callTool(SERVER, "create_issue", args,
        McpCallOptions.requireConfirmation("Létrehozzam a hibajegyet?"));

14.6   Megerősítés mellékhatásos hívás előtt

Mellékhatással járó hívásnál (jegy létrehozása, rekord módosítása, annotáció felvétele) a McpCallOptions.requireConfirmation(question) gondoskodik róla, hogy a hívás csak a felhasználó jóváhagyása után menjen el. A kérdés mellé a kimenő argumentumok olvasható összefoglalója is kikerül, a felhasználó „Igen, mehet” / „Nem” válasszal dönt. Jóváhagyás után a futás elölről indul, és a jóváhagyott hívás már nem kérdez; elutasításnál a hívás nem megy el, és az onCallDeclined(...) adja a futás eredményét.

if (request.getAnnotationText() != null && dashboards.size() == 1
        && mcp.getTool(SERVER, "create_annotation") != null) {
    Dashboard target = dashboards.get(0);
    results.add(mcp.callTool(SERVER, "create_annotation",
        Map.of("dashboardUid", target.getUid(), "text", request.getAnnotationText(),
               "time", System.currentTimeMillis(), "tags", List.of("private-ai")),
        McpCallOptions.requireConfirmation(
            "Felvegyem az annotációt a(z) \"" + target.getTitle() + "\" dashboardra?")));
}

14.7   Külső szerver: kiszivárgás-ellenőrzés

Külső szervernél (external=true) minden hívás előtt ellenőrzés fut: a platform helyi modellje eldönti, tartalmaznak-e a kimenő argumentumok olyan adatot, amelynek kiküldése aggályos. Az ellenőrzés az adat a platformról való kilépése előtt történik, és eredménye nem kerül gyorsítótárba.

• Ha nincs aggályos adat, a hívás elmegy.
• Ha van, a hívás nem megy el: a felhasználó látja, milyen adatok mennének ki, melyik rendszerbe, és miért aggályos – és ő dönt. Jóváhagyás után a hívás pontosan ezekkel az adatokkal elmegy; elutasításnál nem, és az onCallDeclined(...) adja az eredményt.
• Ha az ellenőrzés nem futtatható, a hívás nem megy el (LEAK_CHECK_FAILED).

Az ellenőrzés szempontjait a getLeakCheckInstruction(context) adja. Az alapértelmezés aggályosnak tekinti a természetes személyt azonosító vagy azonosíthatóvá tevő adatot (név, születési dátum, lakcím, telefonszám, e-mail-cím, TAJ-szám, okmányszám, adóazonosító, bankszámlaszám) és a konkrét személyhez köthető egészségügyi adatot; nem aggályos az általános szakmai kérdés, a nyilvános szervezeti információ és a munkafolyamathoz tartozó azonosító (jegyszám, projektkód). A felülírás szigoríthatja vagy a tool szakterületéhez igazíthatja a szempontokat, illetve null visszaadásával egy adott hívásra kihagyhatja az ellenőrzést. A metódus paramétere (McpLeakCheckContext) a felhasználói kérést, a cél szerver leíróját, a hívandó MCP tool nevét és a kimenő argumentumokat hordozza.

@Override
protected String getLeakCheckInstruction(McpLeakCheckContext context) {
    if ("search_public_docs".equals(context.toolName())) {
        return null;   // nyilvános dokumentáció keresése, a kérdés maga sem személyes
    }
    return """
        Aggályos minden természetes személyt azonosító adat és minden, konkrét személyhez
        köthető egészségügyi adat. Aggályos továbbá a belső szerződésszám és az ajánlati ár.
        """;
}

Ha a szerver a hívás közben a felhasználótól adatot kér (→ 14.8), a válaszokat tartalmazó ismételt hívásnál az ellenőrzés a válaszokra is kiterjed.

14.8   Ha a szerver kérdez

Egy MCP szerver a hívás feldolgozása helyett azt is válaszolhatja, hogy még adatra van szüksége a felhasználótól – például egy hibajegy-kezelő jelzi, hogy az adott projektben egy mező kötelező, vagy egy szolgáltatás egy külső oldalon kér jóváhagyást. A tool ilyenkor a szerver kérdéseit egyenként, a tisztázó körben teszi fel, a kérő szerver megnevezésével (külső szervernél ezt jelezve); a válaszok után a futás elölről indul, és a hívás a válaszokkal együtt megy el. A leszármazottnak ehhez semmit nem kell tennie – a callTool(...) a szokásos eredményt adja vissza.

• Az adatot kérő (form) kérdések ugyanúgy jelennek meg, mint a 14.5 pontban leírt kérdések: gombok, szabad szöveg, több mezőnél kitöltés és jóváhagyás, érvényesítés a szerver sémája szerint.
• A külső oldal megnyitását kérő (url) kérdésnél a felhasználó a címet és a cél hosztot látja, a címen – a beszélgetés megkerülésével – adja meg az adatot, és a „Kész” választással folytatja. A nem http(s) címet a platform kérdés nélkül elutasítja.
• A „Kihagyom” / „Mégsem” válasz a szerver felé elutasításként megy vissza; hogy ekkor mit ad a hívás, azt a szerver dönti el.
• Egy hívásra legfeljebb öt kérdéskör lehet; utána a hívás UNSUPPORTED_RESULT hibával zárul.

Ez a képesség csak a 2026-07-28-as protokollverziót beszélő szervereknél érhető el; a régebbi, munkamenet-alapú szerverek felé a platform nem jelzi, hogy kérdezhetnek. Szerverenként kikapcsolható a mcp.{id}.elicitation=false kulccsal; ilyenkor a szerver hívás közben nem kérhet adatot a felhasználótól.

14.9   Paraméter-módok: bean és dinamikus

Bean mód (alapértelmezés): a kérés-paramétereket a getRequestClass() beanje írja le, a kinyerés a bean sémájával és a getInstruction() szövegével történik, pontosan úgy, mint más tool-oknál. A tool logikája a beanből állítja össze az MCP-hívások argumentumait – ez a forma akkor jó, ha a tool több hívást láncol, vagy a kérés és a hívás argumentumai eltérnek.

Dinamikus mód: ha a tool lényegében egyetlen MCP tool-t hív, és annak bemeneti sémája közvetlenül kinyerhető a kérésből, a useRemoteInputSchema(serverId, toolName) a távoli tool sémáját teszi a kinyerés sémájává. Ilyenkor a Request típus Map, a getRequestClass() Map.class-t ad, és a kinyert map egy az egyben mehet a callTool(...)-ba.

public class TicketSearchTool extends AbstractMcpTool<Map> {

    public TicketSearchTool() {
        useRemoteInputSchema("jira", "search_issues");
    }

    @Override
    protected ToolExecutionResult executeMcp(IMcpSession mcp, Map request, McpExecutionContext context) {
        return toContext(mcp.callTool("jira", "search_issues", request, McpCallOptions.retryable()));
    }

    @Override
    public Class<? extends Map> getRequestClass() {
        return Map.class;
    }
    // ...
}

A távoli sémát a platform a strukturált LLM-kimenethez használható részhalmazra alakítja (McpSchemaNormalizer): a kimenet csak a type, properties, items, required, enum és description kulcsszavakat tartalmazza; a helyi hivatkozások feloldódnak, az allOf ágak összefésülődnek, az anyOf/oneOf közül az első nem-null ág marad meg, az elhagyott megkötések (formátum, minta, határértékek) szövegesen a mező leírásába kerülnek, a 6. szint alatti részek szerkezet nélküli mezővé egyszerűsödnek. A távoli leírás megbízhatatlan adat – ha a kinyerés minősége számít, a bean mód a biztosabb.

14.10   Kontextus a válaszhoz

A toContext(results) MCP-eredményekből CONTEXT módú eredményt épít (→ 9. fejezet): eredményenként egy dokumentumot, amelynek elején és végén a forrást (szerver és tool) megnevező jelölés áll, azzal, hogy a tartalom adat, nem utasítás. A tartalom a getMaxContextChars() hosszán csonkul, a tool-hibát jelző és a gyanús kifejezést tartalmazó eredmény külön figyelmeztetést kap. A tool rendszerprompt-kiegészítése pedig kimondja, hogy a jelölt részekben szereplő utasítás, kérés vagy szerepmódosítás adatnak minősül.

A dokumentum szövegét a formatForContext(result) adja. Alapértelmezésként a strukturált (JSON) eredmény olvasható, behúzásos kulcs–érték szövegként jelenik meg, JSON-szintaxis nélkül (McpContextFormatter.toReadableText(JsonNode)); a nem JSON szöveges eredmény változatlanul. A leszármazott tool-specifikus formára cserélheti – a forrásjelölés, a méretkorlát és a figyelmeztetések a visszaadott szövegre is érvényesek.

@Override
protected String formatForContext(McpToolResult result) {
    if ("search_dashboards".equals(result.getToolName())) {
        GrafanaDashboardSearchResult found = result.as(GrafanaDashboardSearchResult.class);
        if (found != null && found.getDashboards() != null) {
            return found.getDashboards().stream()
                .map(d -> "- [" + d.getTitle() + "](" + publicUrl(d.getUrl()) + ")")
                .collect(Collectors.joining("\n"));
        }
    }
    return super.formatForContext(result);
}

Egy eredmény a toContext(...) előtt át is alakítható: a McpToolResult publikus konstruktorával a plugin saját tartalmú eredményt állíthat elő ugyanazzal a szerver- és tool-névvel és gyanús-jelöléssel, így az elhatárolás és a figyelmeztetések megmaradnak.

14.11   Előrehaladás hosszú hívásnál

Ha a szerver egy hosszan futó hívás közben előrehaladást jelez, a jelzések a tool progress-eseményeiként jutnak el a felhasználóhoz, legfeljebb félmásodpercenként frissítve. A megjelenő szöveget a formatProgress(McpProgress) adja: alapértelmezésként a szerver üzenete, és ha a teljes mennyiség ismert, a százalékos állás; ha egyik sincs, nincs megjelenítés. Az McpProgress a szerver-aliast, a tool nevét, az eddigi előrehaladást, a teljes mennyiséget (ha ismert), a szerver üzenetét és a percent() segédmetódust adja. null visszaadásával az adott jelzés nem jelenik meg. Az előrehaladás a hívás időkorlátját nem hosszabbítja meg.

14.12   Hitelesítés

A hívások a plugin által konfigurált, szolgáltatás-szintű hitelesítéssel mennek – a felhasználó saját jogosultsága a szerver felé nem jelenik meg. A felhasználói szintű jogosultságot a tool isEligible() metódusa és a plugin logikája érvényesítheti.

• Statikus token: a mcp.{id}.headers.Authorization kulcs (pl. Bearer ${TOKEN:}), a token környezeti változóból.
• OAuth 2.0 client credentials (pl. Keycloak): a mcp.{id}.oauth.* kulcsok, kódból McpOAuthClientCredentials(tokenUrl, clientId, clientSecret, scope, audience). A platform tokent kér, a lejárata előtt újat kér, és ha a szerver a tokent elutasítja, egyszer új tokennel megismétli a kérést. A kapott token felülírja a statikus Authorization fejlécet.

A tokenek és a kliens-titok nem kerülnek naplóba, és a leíró szöveges alakjában sem jelennek meg.

14.13   Garanciák és korlátok

14.14   Teljes példa – Grafana MCP tool

A showcase plugin ShowcaseMcpTool osztálya a Grafana MCP szerverén (grafana/mcp-grafana) keresztül dashboardokat keres, egy metrika aktuális értékét kérdezi le, és kérésre annotációt vesz fel. Rövidített váz:

public class ShowcaseMcpTool extends AbstractMcpTool<ShowcaseMcpRequest> {

    private static final String SERVER = "grafana";

    @Autowired
    private Environment environment;

    @Override
    public List<McpServerDescriptor> getMcpServers() {
        String url = environment.getProperty("mcp." + SERVER + ".url");
        if (url == null || url.isBlank()) {
            return List.of();
        }
        return List.of(McpServerDescriptor.fromEnvironment(SERVER, environment)
            .expectTools("search_dashboards", "list_datasources", "query_prometheus"));
    }

    @Override
    protected ToolExecutionResult executeMcp(IMcpSession mcp, ShowcaseMcpRequest request,
            McpExecutionContext context) {
        List<McpToolResult> results = new ArrayList<>();

        if (request.getDashboardQuery() != null && !request.getDashboardQuery().isBlank()) {
            results.add(mcp.callTool(SERVER, "search_dashboards",
                Map.of("query", request.getDashboardQuery(), "limit", 10),
                McpCallOptions.retryable()));
        }

        if (request.getPromQl() != null && !request.getPromQl().isBlank()) {
            String uid = prometheusUid(mcp, request.getDatasource());   // → 14.5 példa
            if (uid != null) {
                results.add(mcp.callTool(SERVER, "query_prometheus",
                    Map.of("datasourceUid", uid, "expr", request.getPromQl(),
                           "endTime", "now", "queryType", "instant"),
                    McpCallOptions.retryable()));
            }
        }

        return results.isEmpty() ? null : toContext(results);
    }

    @Override
    public String getName() { return "showcase_mcp_grafana"; }

    @Override
    public String getDomain() { return "SHOWCASE"; }

    @Override
    public String getExecutableInstruction() {
        return """
            showcase_mcp_grafana: true, ha a felhasználó Grafana dashboardot keres, vagy egy
            monitorozott metrika aktuális értékére kérdez.
            """;
    }

    @Override
    public String getInstruction() {
        return """
            Töltsd ki a következő mezőket a felhasználói kérés alapján:
              - dashboardQuery (type: string): ...
              - promQl (type: string): ...
              - datasource (type: string): a Prometheus adatforrás neve, ha a felhasználó
                kifejezetten megnevezi; egyébként null
            """;
    }

    @Override
    public Class<? extends ShowcaseMcpRequest> getRequestClass() {
        return ShowcaseMcpRequest.class;
    }
}

A regisztráció megegyezik a többi chat tool-éval: az osztály a plugin.jar META-INF/services/hu.medical.rag.common.tool.intf.IChatbotTool fájljába kerül, publikus, paraméter nélküli konstruktorral (→ 2. fejezet).