ERPIO One MCP – dokumentace

Co potřebujete

• Číslo zákazníka v ERPIO One (např. 1459).
• Přístupový klíč e1key z ERPIO One – vygenerujete ho v ERPIO One, případně vám ho poskytne správce. AI bude mít stejná oprávnění jako uživatel, kterému klíč patří.
• Správce musí mít pro vaše číslo zákazníka nastavené metody (viz část pro správce).

Klíč e1key chraňte jako heslo. Kdo ho má, pracuje v ERPIO One s vašimi oprávněními. Klíč nikomu neposílejte a nevkládejte ho do textu konverzace s AI.

Claude (claude.ai, desktop, mobil)

Vlastní konektory jsou dostupné v plánech Pro, Max, Team a Enterprise.

1. Otevřete Nastavení → Konektory a klikněte na Přidat vlastní konektor (v plánech Team/Enterprise konektor nejprve přidá vlastník v Admin settings → Connectors, členové ho pak jen připojí).
2. Název: např. ERPIO. URL: https://clientmcp.erpio.one/{customerId}. Pokročilá nastavení (OAuth Client ID/Secret) nechte prázdná.
3. Klikněte Přidat a poté Připojit. Otevře se přihlašovací stránka ERPIO One – zadejte e1key a klikněte Povolit přístup.
4. V konverzaci zapněte konektor přes tlačítko + → Konektory → ERPIO.

Zkuste například: „Najdi obchodní zakázku pro A2B a zapiš k ní úkol na zítra – poslat cenovou nabídku." U nástrojů, které mění data, se Claude před provedením zeptá na potvrzení.

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

ChatGPT

Možnost 1: MCP aplikace (developer mode)

Plná podpora včetně zápisových akcí je v plánech Business, Enterprise a Edu (Pro jen čtení). Developer mode zapíná správce workspace.

1. Settings → Apps → Advanced settings – zapněte Developer mode.
2. Apps → Create: zadejte název a MCP adresu https://clientmcp.erpio.one/{customerId}, autentizace OAuth.
3. Klikněte Scan Tools, přihlaste se e1key na přihlašovací stránce ERPIO One.

Možnost 2: Custom GPT s Actions (OpenAPI)

1. V editoru GPT otevřete Configure → Actions → Create new action.
2. Import from URL bez klíče nefunguje – stáhněte specifikaci v administraci (stáhnout specifikaci) a vložte její obsah do pole Schema.
3. Authentication → API Key, typ Bearer, hodnota = váš e1key.

Akce, které mění data, jsou ve specifikaci označené x-openai-isConsequential – ChatGPT se před jejich provedením zeptá. Po změně metod v administraci specifikaci v GPT vyměňte.

Open WebUI

1. Jako správce otevřete Admin Settings → External Tools (příp. Integrations) a klikněte + Add Connection.
2. Type: MCP (Streamable HTTP) – ne OpenAPI.
3. URL: https://clientmcp.erpio.one/{customerId}/mcp
4. Auth: Bearer, Key: váš e1key. Uložte.
5. V Access Control určete, kteří uživatelé nebo skupiny mohou nástroje používat, a zapněte je u modelu nebo v chatu.

V Open WebUI zadává spojení správce pro všechny – všichni uživatelé s přístupem pracují pod jedním e1key. Pokud má mít každý vlastní oprávnění, vytvořte samostatná spojení a omezte je přes Access Control.

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

Jiní MCP klienti (Cursor, VS Code, Windsurf, vlastní aplikace…)

Server podporuje transport Streamable HTTP (bezstavový, bez SSE). Většina klientů přijme konfiguraci ve tvaru:

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

• Místo Bearer můžete poslat i hlavičku Authorization: e1key VAS_E1KEY.
• Klienti s podporou OAuth 2.1 (dynamická registrace, PKCE) mohou použít adresu bez klíče – přihlásí se přes přihlašovací stránku.
• Nesprávný klíč vrátí hned při připojení HTTP 401.

OpenAI API (Responses API)

Model OpenAI může nástroje ERPIO volat přímo přes vestavěný nástroj mcp. Klíč se posílá 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": "Najdi obchodní zakázky pro A2B"
  }'

require_approval: "always" vyžaduje schválení každého volání – doporučujeme u zápisových nástrojů. Pomocí allowed_tools můžete povolit jen vybrané nástroje. Stejně funguje i jiné OpenAI-kompatibilní API s podporou MCP.

REST / OpenAPI (n8n, Make, Power Automate, vlastní integrace)

• Specifikace: GET https://clientmcp.erpio.one/{customerId}/openapi.json (s hlavičkou Authorization: Bearer {e1key}).
• Volání nástroje: POST https://clientmcp.erpio.one/{customerId}/tools/{nazev_nastroje}, tělo = JSON s argumenty.

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 }'

Odpověď: { "data": …, "hasMore": true, "nextRowsOffset": 20 }. Chyby: { "error": { "code", "message", "correlationId" } } se stavem 400 (argumenty), 401 (klíč), 403 (oprávnění), 404 (nástroj), 429 (limit), 502 (ERPIO).

Společné argumenty metod pro čtení: search (vyhledávání), rows_offset a rows_count (stránkování, max 1000).

Řešení problémů

AI nevidí nový nástroj

Klienti si seznam nástrojů pamatují. Konektor odpojte a znovu připojte (v Claude Nastavení → Konektory), v Open WebUI spojení znovu uložte, u OpenAPI znovu načtěte specifikaci. Zkontrolujte také, zda je metoda v administraci aktivní a u zápisové metody zda je povolen zápis.

401 / „Nesprávný e1key"

Klíč je neplatný, zrušený nebo nepatří k danému číslu zákazníka.

„Překročen limit volání"

ERPIO One omezuje počet volání za minutu. Chvíli počkejte; u velkých seznamů použijte search místo stahování všech řádků.

AI odmítá zapisovat

Zápisové nástroje jsou zveřejněny jen tehdy, když má správce zapnuto Povolit zápisové metody. Klient se před zápisem ptá na potvrzení.

Přihlášení do administrace

Otevřete https://clientmcp.erpio.one/{customerId}/admin a přihlaste se klíčem e1key. Nastavení platí pro celé číslo zákazníka – pro všechny, kdo se připojí.

Na úvodní stránce najdete adresy konektoru pro jednotlivé klienty, seznam metod, přidání nové metody a nastavení (Povolit zápisové metody, Doplňující instrukce pro AI).

Přidání metody

1. Do pole Přidat metodu vložte URL metody klientského API, např. https://client.erpio.one/api/v1/{customerId}/apiobchodnezakazky, nebo jen alias či ID akce.
2. Server načte metadata akce z ERPIO One a vytvoří nástroj s parametry (typy, výchozí hodnoty, číselníky, skryté systémové parametry).
3. Otevře se úprava metody – doplňte popisy a nastavte, zda metoda pouze čte.

Nová metoda je z bezpečnostních důvodů označena jako zápisová, dokud ji neoznačíte Pouze čtení.

Úprava metody a parametrů

Parametry

• Popis a typ hodnoty – typ se předvyplní z metadat (text, číslo, datum, datum a čas, ano/ne, soubor…).
• Povinný – AI ho musí vyplnit.
• Výchozí hodnota – pošle se, pokud AI parametr nezadá.
• Pevná hodnota – pošle se vždy a AI parametr nevidí (např. vždy konkrétní středisko).
• Skrytý před AI – systémové parametry (např. přihlášený uživatel) doplňuje ERPIO.
• Povolené hodnoty – seznam oddělený čárkou.
• Číselník – akce (alias/ID), sloupec hodnoty a sloupec popisu. Malé číselníky dostane AI přímo jako seznam, u velkých použije nástroj erpio_lookup_values. Doplňované parametry (např. @TypPopis=Popis) server vyplní z vybraného řádku číselníku.
• Obnovit z metadat – načte změny definice akce v ERPIO One a zachová vaše popisy.

Jak psát popisy

AI nevidí, co akce v ERPIO dělá – ví jen to, co napíšete. Dobrý popis řekne co metoda dělá, kdy ji použít a odkud vzít hodnoty parametrů.

• U dat uveďte, co znamenají (termín, datum vytvoření…).
• Zmiňte souvislosti mezi metodami („číslo zakázky vezmi z …").
• Do Doplňujících instrukcí pro AI napište pravidla platná pro všechny metody (např. „aktivity zapisuj vždy s popisem").

AI návrh popisů

Pokud je funkce na serveru zapnutá, na stránce metody je tlačítko ✦ Navrhnout popisy (AI). Nejprve vyplňte pole K čemu metodu používáte jednou větou – výrazně to zlepší výsledek.

• AI vyplní popis metody, popisy parametrů a odhad povinných parametrů a „pouze čtení". Pole se zvýrazní.
• Nic se neuloží automaticky – zkontrolujte, upravte a klikněte Uložit (nebo obnovte stránku a návrh zahoďte).
• Do AI jde pouze struktura akce (názvy, popisky a typy parametrů) a vaše poznámka – žádné hodnoty ani data z ERPIO. Do poznámky nepište konkrétní údaje zákazníků.

Zápisové metody

• Metody, které nejsou označené Pouze čtení, se AI nabídnou až po zapnutí Povolit zápisové metody.
• Klienti je dostanou s označením „mění data" a před provedením se ptají uživatele na potvrzení.
• Každé zápisové volání se zapisuje do auditního logu na serveru (čas, nástroj, parametry, výsledek).

Test a náhled

• Test volání – vyplňte hodnoty tak, jak by je poslala AI, a podívejte se na výsledek z ERPIO One. Test zápisové metody reálně zapíše data – je třeba ho potvrdit zaškrtnutím.
• Jak nástroj uvidí AI – přesná definice, kterou dostane klient (název, popis, schéma parametrů).
• Po změnách upozorněte uživatele, aby konektor znovu připojili, pokud nový nástroj nevidí.