# MCP-integráció

> Csatlakozz OAuth 2.1-et támogató MCP-klienssel a Komashi általános végpontjához, válassz szolgáltatót, és kezeld a katalógust, ügyfeleket és előfizetéseket.

Canonical: https://komashi.com/docs/hu/provider/Developers/mcp-integration/
Language: hu

A Komashi Model Context Protocol (MCP) szerverével egy kompatibilis AI-asszisztens felderítheti az elérhető eszközöket, és dolgozhat a hozzáférhető vállalkozásaid adataival. A támogatott területek közé tartozik a katalógus, a szolgáltató- és szolgáltatásbeállítás, az ügyfelek, kapcsolattartók, előfizetések, számlák és a felhasználás kezelése.

## Általános MCP-végpont

A Komashi általános MCP-végpontját használd:

```text
https://mcp.komashi.com/
```

Ez az útmutató végig ezt a gyökérvégpontot használja. Saját vagy helyi telepítésnél annak beállított MCP-domainjét add meg, ugyanígy a gyökérútvonallal. Az MCP-címet ne a REST API végpontjából állítsd elő, és ne egészítsd ki REST-verzióútvonallal.

## Hitelesítés: OAuth 2.1

Az MCP **a felhasználói fiókodat hitelesíti OAuth 2.1 kapcsolattal**, `mcp:use` jogosultsági körrel. Az **Integráció → API** oldalon létrehozott szolgáltatói REST API-kulcs más típusú hozzáférés; ehhez az MCP-kapcsolathoz nem azt kell megadni.

1. Vegyél fel egy távoli MCP-szervert olyan kliensben, amely támogatja a HTTP-alapú kapcsolatot és az OAuth-hitelesítést.
2. Végpontként add meg a `https://mcp.komashi.com/` címet.
3. Indítsd el a kliens csatlakozási vagy engedélyezési folyamatát.
4. Jelentkezz be abba a Komashi-fiókba, amelynek a szolgáltatóit el szeretnéd érni.
5. Nézd át a hozzáférési kérelmet, és engedélyezd a kapcsolatot, ha a megjelölt alkalmazást szeretnéd csatlakoztatni.
6. Térj vissza a klienshez, és várd meg az elérhető eszközök felderítését.

Az OAuth hozzáférési és frissítési tokenjeit a kliens kezeli. Ne másolj szolgáltatói API-kulcsot olyan mezőbe, amely OAuth-engedélyezést vár.

Egyes kliensekben a távoli szerver konfigurációja például ilyen:

```json
{
  "mcpServers": {
    "komashi": {
      "type": "http",
      "url": "https://mcp.komashi.com/"
    }
  }
}
```

A pontos formátum kliensenként eltér. Ez a példa a végpontot adja meg; az engedélyezést továbbra is a kliens OAuth-folyamatában kell elvégezni. A csak statikus Bearer kulcsot fogadó kliens ehhez önmagában nem elegendő.

## A vállalkozás kiválasztása

A kapcsolat a bejelentkezett felhasználóhoz kapcsolt szolgáltatókat érheti el. Több szolgáltató esetén:

1. Kérd meg az asszisztenst a hozzáférhető Komashi-szolgáltatók listázására.
2. Válaszd ki a vállalkozást, amellyel dolgozni szeretnél.
3. Az asszisztens válassza ki ezt a szolgáltatót a szolgáltatóspecifikus műveletek előtt.

A szerver `PROVIDER_SELECTION_REQUIRED` eredményt adhat vissza a lehetséges szolgáltatókkal. Ez a munkakörnyezet kiválasztását kéri, nem kapcsolódási hiba. A kiválasztás nem ad hozzáférést a fiókod aktív tagságain kívüli vállalkozásokhoz. Ha pontosan egy szolgáltató érhető el, azt a szerver automatikusan is kiválaszthatja.

Saját kliens fejlesztésekor a szolgáltatói környezet az `X-Komashi-Provider` fejlécben is megadható. A jogosult fiókhoz visszakapott szolgáltatóazonosítót használd, ne a megjelenített nevet vagy az aldomaint.

## Elérhető feladatok

| Terület | Jellemző műveletek |
| --- | --- |
| Szolgáltató és szolgáltatás beállítása | Tervezetek előkészítése és böngészős folytatási link visszaadása az áttekintéshez. |
| Katalógus | Szolgáltatások, csomagok, időszakok, kiegészítők, opciók és kedvezmények lekérdezése. |
| Ügyfelek | Ügyfelek és kapcsolattartók listázása, létrehozása, megtekintése, módosítása és törlése; támogatott ügyfélelérési linkek készítése. |
| Előfizetések | Lekérdezés és létrehozás, elérhető fizetési linkek készítése, csomagváltás, támogatott dátumok és állapot módosítása, előfizetés vagy függő változtatás lemondása. |
| Felhasználás | Egyedi vagy csoportos felhasználás ellenőrzése, abszolút összesítés beállítása, növelés és csökkentés. |
| Számlák | Számlaadatok listázása és megtekintése. |
| Jogi tervezetek | A támogatott dokumentumtervezetek előkészítése áttekintésre. |

Az elérhető műveleteket a szolgáltatói hozzáférésed, szerepköröd, az eszköz ellenőrzései és az aktuális üzleti állapot is korlátozza. A kötelező mezőket a szerver által felderített eszközsémából olvasd ki; ne feltételezd, hogy minden eszköz csak olvas.

A beállítóeszközök tervezetet készíthetnek, és folytatási linket adhatnak vissza. A kapott Komashi-linket nyisd meg a végleges áttekintéshez és befejezéshez. A tervezet vagy a link önmagában nem jelenti azt, hogy a szolgáltató vagy a szolgáltatás véglegesen létrejött.

### Példakérések az asszisztenshez

- „Listázd a Komashi-vállalkozásaimat, és engedd kiválasztani a megfelelőt.”
- „Mutasd meg a kiválasztott vállalkozás szolgáltatásait, csomagjait és időszakait.”
- „Keresd meg ennek az ügyfélnek az előfizetéseit, és magyarázd el az állapotukat.”
- „Ellenőrizd, mennyi felhasználási keret maradt ennél az előfizetésnél.”
- „Készíts egy új szolgáltatástervezetet, és a folytatás előtt mutasd meg az összefoglalót.”

Felhasználás szinkronizálásakor abszolút összesítést adj meg. Növeléshez vagy csökkentéshez a módosító műveletet használd. Bizonytalan eredményű kérés megismétlése előtt kérdezd le az aktuális állapotot.

## Integrációs erőforrások

Az általános végpont az alábbi MCP-erőforrásokat teszi elérhetővé:

| URI | Tartalom |
| --- | --- |
| `komashi://resources/openapi-docs` | Az elérhető OpenAPI-dokumentum. |
| `komashi://resources/integration-guide` | Az integráció munkafolyamatának útmutatója. |

Elérhető a `guide-app-integration-prompt` munkafolyamat-prompt is. Az erőforrások és promptok megjelenítése kliensfüggő; ha a kliens csak eszközöket jelenít meg, az eszközfelderítéssel kezdd.

## Kapcsolatok kezelése és leválasztása

A Komashiban nyisd meg a fiókod **Beállítások → MCP** részét. Az **Aktív MCP-kapcsolatok** felsorolja a csatlakoztatott alkalmazást, kliensnevet, kapcsolódási időt, az esetleges lejáratot és a céloldalak domainjeit.

A megfelelő kapcsolatnál kattints a **Leválasztás** gombra, majd erősítsd meg. Ez visszavonja a hozzáférési és frissítési tokenjét. Újracsatlakozáshoz ismét OAuth-engedélyezés kell. A szolgáltatói REST API-kulcs törlése nem választja le a fiókszintű OAuth MCP-kapcsolatot.

## Hibaelhárítás

| Tünet | Teendő |
| --- | --- |
| `401` vagy ismétlődő bejelentkezés | Csatlakozz újra a kliens OAuth-folyamatával. Ellenőrizd a `https://mcp.komashi.com/` végpontot. |
| Hiányzó `mcp:use` jogosultsági kör / `403` | Engedélyezd újra az MCP-hozzáférést, és ellenőrizd a szolgáltatói tagságot, szerepkört. |
| `PROVIDER_SELECTION_REQUIRED` | Válassz a visszaadott szolgáltatók közül, majd ismételd meg az eredeti feladatot. |
| Nem található rekord / `404` | Ellenőrizd a kiválasztott szolgáltatót és az ahhoz tartozó azonosítót. |
| `409` vagy `422` | Az eszköz hibaüzenete alapján javítsd az állapotütközést vagy a mezőket. |
| Kapcsolódik, de nincsenek eszközök | Ellenőrizd a távoli HTTP MCP és az OAuth támogatását. Ne helyi stdio-parancsként állítsd be a szervert. |

Kapcsolódó útmutatók: [Fejlesztői áttekintés](https://komashi.com/docs/hu/provider/Developers/who-is-a-developer/index.md), [REST API-integráció](https://komashi.com/docs/hu/provider/Developers/api-integration/index.md), [API-kulcsok](https://komashi.com/docs/hu/provider/Settings/10api/index.md).