ERPIO One MCP – dokumentácia

Čo potrebujete

• Číslo zákazníka v ERPIO One (napr. 1459).
• Prístupový kľúč e1key z ERPIO One – vygenerujete ho v ERPIO One, prípadne vám ho poskytne správca. AI bude mať rovnaké oprávnenia ako používateľ, ktorému kľúč patrí.
• Správca musí mať pre vaše číslo zákazníka nastavené metódy (pozri časť pre správcu).

Kľúč e1key chráňte ako heslo. Kto ho má, pracuje v ERPIO One s vašimi oprávneniami. Kľúč nikomu neposielajte a nevkladajte ho do textu konverzácie s AI.

Claude (claude.ai, desktop, mobil)

Vlastné konektory sú dostupné v plánoch Pro, Max, Team a Enterprise.

1. Otvorte Nastavenia → Konektory a kliknite na Pridať vlastný konektor (v plánoch Team/Enterprise konektor najprv pridá vlastník v Admin settings → Connectors, členovia ho potom len pripoja).
2. Názov: napr. ERPIO. URL: https://clientmcp.erpio.one/{customerId}. Rozšírené nastavenia (OAuth Client ID/Secret) nechajte prázdne.
3. Kliknite Pridať a potom Pripojiť. Otvorí sa prihlasovacia stránka ERPIO One – zadajte e1key a kliknite Povoliť prístup.
4. V konverzácii zapnite konektor cez tlačidlo + → Konektory → ERPIO.

Skúste napríklad: „Nájdi obchodnú zákazku pre A2B a zapíš k nej úlohu na zajtra – poslať cenovú ponuku." Pri nástrojoch, ktoré menia dáta, sa Claude pred vykonaním spýta na potvrdenie.

Claude Code (príkazový riadok): claude mcp add --transport http erpio https://clientmcp.erpio.one/{customerId}/mcp --header "Authorization: Bearer VAS_E1KEY"

ChatGPT

Možnosť 1: MCP aplikácia (developer mode)

Plná podpora vrátane zápisových akcií je v plánoch Business, Enterprise a Edu (Pro len čítanie). Developer mode zapína správca workspace.

1. Settings → Apps → Advanced settings – zapnite Developer mode.
2. Apps → Create: zadajte názov a MCP adresu https://clientmcp.erpio.one/{customerId}, autentifikácia OAuth.
3. Kliknite Scan Tools, prihláste sa e1key na prihlasovacej stránke ERPIO One.

Možnosť 2: Custom GPT s Actions (OpenAPI)

1. V editore GPT otvorte Configure → Actions → Create new action.
2. Import from URL nefunguje bez kľúča – stiahnite špecifikáciu v administrácii (stiahnuť špecifikáciu) a vložte jej obsah do poľa Schema.
3. Authentication → API Key, typ Bearer, hodnota = váš e1key.

Akcie, ktoré menia dáta, sú v špecifikácii označené x-openai-isConsequential – ChatGPT sa pred ich vykonaním spýta. Po zmene metód v administrácii špecifikáciu v GPT vymeňte.

Open WebUI

1. Ako správca otvorte Admin Settings → External Tools (príp. Integrations) a kliknite + Add Connection.
2. Type: MCP (Streamable HTTP) – nie OpenAPI.
3. URL: https://clientmcp.erpio.one/{customerId}/mcp
4. Auth: Bearer, Key: váš e1key. Uložte.
5. V Access Control určite, ktorí používatelia alebo skupiny môžu nástroje používať, a zapnite ich pri modeli alebo v chate.

V Open WebUI zadáva spojenie správca pre všetkých – všetci používatelia s prístupom pracujú pod jedným e1key. Ak má mať každý vlastné oprávnenia, vytvorte samostatné spojenia a obmedzte ich cez Access Control.

Alternatíva: Type OpenAPI, URL https://clientmcp.erpio.one, cesta /{customerId}/openapi.json, Auth Bearer = e1key.

Iní MCP klienti (Cursor, VS Code, Windsurf, vlastné aplikácie…)

Server podporuje transport Streamable HTTP (bezstavový, bez SSE). Väčšina klientov akceptuje konfiguráciu v tvare:

{
  "mcpServers": {
    "erpio": {
      "url": "https://clientmcp.erpio.one/{customerId}/mcp",
      "headers": { "Authorization": "Bearer VAS_E1KEY" }
    }
  }
}

• Namiesto Bearer môžete poslať aj hlavičku Authorization: e1key VAS_E1KEY.
• Klienti s podporou OAuth 2.1 (dynamická registrácia, PKCE) môžu použiť adresu bez kľúča – prihlásia sa cez prihlasovaciu stránku.
• Nesprávny kľúč vráti hneď pri pripojení HTTP 401.

OpenAI API (Responses API)

Model OpenAI môže nástroje ERPIO volať priamo cez vstavaný nástroj mcp. Kľúč sa posiela v poli authorization:

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "<model>",
    "tools": [{
      "type": "mcp",
      "server_label": "erpio",
      "server_url": "https://clientmcp.erpio.one/{customerId}/mcp",
      "authorization": "VAS_E1KEY",
      "require_approval": "always"
    }],
    "input": "Nájdi obchodné zákazky pre A2B"
  }'

require_approval: "always" vyžaduje schválenie každého volania – odporúčame pri zápisových nástrojoch. Pomocou allowed_tools môžete povoliť len vybrané nástroje. Rovnako funguje aj iné OpenAI-kompatibilné API s podporou MCP.

REST / OpenAPI (n8n, Make, Power Automate, vlastné integrácie)

• Špecifikácia: GET https://clientmcp.erpio.one/{customerId}/openapi.json (s hlavičkou Authorization: Bearer {e1key}).
• Volanie nástroja: POST https://clientmcp.erpio.one/{customerId}/tools/{nazov_nastroja}, telo = JSON s argumentmi.

curl -X POST https://clientmcp.erpio.one/{customerId}/tools/obchodne_zakazky_api \
  -H "Authorization: Bearer VAS_E1KEY" \
  -H "Content-Type: application/json" \
  -d '{ "search": "A2B", "rows_count": 20 }'

Odpoveď: { "data": …, "hasMore": true, "nextRowsOffset": 20 }. Chyby: { "error": { "code", "message", "correlationId" } } so stavom 400 (argumenty), 401 (kľúč), 403 (oprávnenie), 404 (nástroj), 429 (limit), 502 (ERPIO).

Spoločné argumenty metód na čítanie: search (vyhľadávanie), rows_offset a rows_count (stránkovanie, max 1000).

Riešenie problémov

AI nevidí nový nástroj

Klienti si zoznam nástrojov pamätajú. Konektor odpojte a znova pripojte (v Claude Nastavenia → Konektory), v Open WebUI spojenie uložte znova, pri OpenAPI znova načítajte špecifikáciu. Skontrolujte aj, či je metóda v administrácii aktívna a pri zápisovej metóde či je povolený zápis.

401 / „Nesprávny e1key"

Kľúč je neplatný, zrušený alebo nepatrí k danému číslu zákazníka.

„Prekročený limit volaní"

ERPIO One obmedzuje počet volaní za minútu. Počkajte chvíľu; pri veľkých zoznamoch použite search namiesto sťahovania všetkých riadkov.

AI odmieta zapisovať

Zápisové nástroje sú zverejnené iba vtedy, keď má správca zapnuté Povoliť zápisové metódy. Klient sa pred zápisom pýta na potvrdenie.

Prihlásenie do administrácie

Otvorte https://clientmcp.erpio.one/{customerId}/admin a prihláste sa kľúčom e1key. Nastavenia platia pre celé číslo zákazníka – pre všetkých, ktorí sa pripoja.

Na úvodnej stránke nájdete adresy konektora pre jednotlivých klientov, zoznam metód, pridanie novej metódy a nastavenia (Povoliť zápisové metódy, Doplňujúce inštrukcie pre AI).

Pridanie metódy

1. Do poľa Pridať metódu vložte URL metódy klientského API, napr. https://client.erpio.one/api/v1/{customerId}/apiobchodnezakazky, alebo len alias či ID akcie.
2. Server načíta metadáta akcie z ERPIO One a vytvorí nástroj s parametrami (typy, predvolené hodnoty, číselníky, skryté systémové parametre).
3. Otvorí sa úprava metódy – doplňte popisy a nastavte, či metóda iba číta.

Nová metóda je z bezpečnostných dôvodov označená ako zápisová, kým ju neoznačíte Iba čítanie.

Úprava metódy a parametrov

Parametre

• Popis a typ hodnoty – typ sa predvyplní z metadát (text, číslo, dátum, dátum a čas, áno/nie, súbor…).
• Povinný – AI ho musí vyplniť.
• Predvolená hodnota – pošle sa, ak AI parameter nezadá.
• Pevná hodnota – pošle sa vždy a AI parameter nevidí (napr. vždy konkrétne stredisko).
• Skrytý pred AI – systémové parametre (napr. prihlásený používateľ) dopĺňa ERPIO.
• Povolené hodnoty – zoznam oddelený čiarkou.
• Číselník – akcia (alias/ID), stĺpec hodnoty a stĺpec popisu. Malé číselníky dostane AI priamo ako zoznam, pri veľkých použije nástroj erpio_lookup_values. Doplňované parametre (napr. @TypPopis=Popis) server vyplní zo zvoleného riadku číselníka.
• Obnoviť z metadát – načíta zmeny definície akcie v ERPIO One a zachová vaše popisy.

Ako písať popisy

AI nevidí, čo akcia v ERPIO robí – vie len to, čo napíšete. Dobrý popis povie čo metóda robí, kedy ju použiť a odkiaľ vziať hodnoty parametrov.

• Pri dátumoch uveďte, čo znamenajú (termín, dátum vytvorenia…).
• Spomeňte súvislosti medzi metódami („číslo zákazky vezmi z …").
• Do Doplňujúcich inštrukcií pre AI napíšte pravidlá platné pre všetky metódy (napr. „aktivity zapisuj vždy s popisom").

AI návrh popisov

Ak je funkcia na serveri zapnutá, na stránke metódy je tlačidlo ✦ Navrhnúť popisy (AI). Najprv vyplňte pole Na čo metódu používate jednou vetou – výrazne to zlepší výsledok.

• AI vyplní popis metódy, popisy parametrov a odhad povinných parametrov a „iba čítanie". Polia sa zvýraznia.
• Nič sa neuloží automaticky – skontrolujte, upravte a kliknite Uložiť (alebo obnovte stránku a návrh zahoďte).
• Do AI ide iba štruktúra akcie (názvy, popisky a typy parametrov) a vaša poznámka – žiadne hodnoty ani dáta z ERPIO. Do poznámky nepíšte konkrétne údaje zákazníkov.

Zápisové metódy

• Metódy, ktoré nie sú označené Iba čítanie, sa AI ponúknu až po zapnutí Povoliť zápisové metódy.
• Klienti ich dostanú s označením „mení dáta" a pred vykonaním sa pýtajú používateľa na potvrdenie.
• Každé zápisové volanie sa zapisuje do auditného logu na serveri (čas, nástroj, parametre, výsledok).

Test a náhľad

• Test volania – vyplňte hodnoty tak, ako by ich poslala AI, a pozrite si výsledok z ERPIO One. Test zápisovej metódy reálne zapíše dáta – treba ho potvrdiť zaškrtnutím.
• Ako nástroj uvidí AI – presná definícia, ktorú dostane klient (názov, popis, schéma parametrov).
• Po zmenách upozornite používateľov, aby konektor znova pripojili, ak nový nástroj nevidia.