MCP-integráció

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:

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.

Vegyél fel egy távoli MCP-szervert olyan kliensben, amely támogatja a HTTP-alapú kapcsolatot és az OAuth-hitelesítést.
Végpontként add meg a https://mcp.komashi.com/ címet.
Indítsd el a kliens csatlakozási vagy engedélyezési folyamatát.
Jelentkezz be abba a Komashi-fiókba, amelynek a szolgáltatóit el szeretnéd érni.
Nézd át a hozzáférési kérelmet, és engedélyezd a kapcsolatot, ha a megjelölt alkalmazást szeretnéd csatlakoztatni.
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:

{
  "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:

Kérd meg az asszisztenst a hozzáférhető Komashi-szolgáltatók listázására.
Válaszd ki a vállalkozást, amellyel dolgozni szeretnél.
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, REST API-integráció, API-kulcsok.