MCP server

TAS vystavuje své AI nástroje externím MCP klientům (Claude Code, Claude Desktop, claude.ai, MCP Inspector) přes jeden HTTP endpoint. Tento článek popisuje, jak vydat přístup, jak zvolit rozsah nástrojů a jak připojit konkrétního klienta. Funkce je dostupná od verze 5.19; článek popisuje stav ve verzi 5.19.4.

Předpoklady

• TAS ve verzi 5.19 nebo novější,
• role Admin nebo API Token Administrator pro přístup k obrazovce API Access,
• systémový uživatel, pod jehož identitou budou nástroje běžet (u API tokenu a confidential OAuth klienta),
• MCP klient, který umí Streamable HTTP transport.

Co MCP server umožňuje

Model Context Protocol je standard, kterým AI klient objevuje a volá nástroje cizí aplikace. TAS ven vystavuje stejný katalog nástrojů, jaký používá jeho vlastní AI chat. Připojený klient tak umí například založit případ, dohledat existující případ v přehledech uživatele, přečíst znalostní dokumenty organizace nebo spustit ruční událost workflow.

Server je bezestavový. Každý požadavek vytvoří novou instanci MCP serveru, vyřídí jednu JSON-RPC zprávu a zavře se. TAS si neudržuje žádné session ID ani stav mezi voláními, kontinuitu drží klient.

Adresa endpointu

Endpoint sedí na backendu, ne na doméně frontendu. Na části instalací je backend proxovaný pod cestou /api, takže adresa je https://<instance>/api/mcp. Jinde backend běží na rootu a adresa je https://<instance>/mcp.

Správnou adresu zjistíte z discovery dokumentu, který odpovídá na obou originech:

curl -s https://<instance>/.well-known/oauth-protected-resource

Odpověď:

{
  "resource": "https://<instance>/api",
  "authorization_servers": ["https://<instance>/api"],
  "bearer_methods_supported": ["header"],
  "resource_name": "tas"
}

Hodnota resource je základní adresa backendu. MCP endpoint je <resource>/mcp.

Rychlý start

1. Vydejte API token. V TAS přejděte na Administrace > API Access > API Tokens a klikněte na Generate Token. Vyberte systémového uživatele, platnost ve dnech a popis.
2. Ověřte spojení voláním metody initialize (viz níže).
3. Připojte klienta podle sekce Připojení klientů.

Ověřovací volání:

curl -s -X POST https://<instance>/api/mcp \
  -H "Authorization: Bearer $TAS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
        "protocolVersion":"2025-06-18","capabilities":{},
        "clientInfo":{"name":"curl","version":"1"}}}'

Očekávaná odpověď:

{"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},
 "serverInfo":{"name":"tas-mcp-server","version":"5.19.4",
 "instructions":"tas stateless MCP server exposing local integration tools."},
 "jsonrpc":"2.0","id":1}

Vydání přístupu

Všechny druhy přístupu se spravují na obrazovce API Access (/administration/api-access), rozdělené do tří záložek: API Tokens, OAuth Clients a OAuth Grants.

Který druh přístupu zvolit

Vydání API tokenu

1. Přejděte na Administrace > API Access > API Tokens.
2. Klikněte na Generate Token.
3. V poli System user vyberte systémového uživatele. Token nemá vlastní oprávnění, dědí role tohoto uživatele.
4. Vyplňte Expiration (days) a Description.
5. Potvrďte tlačítkem Generate Token a token zkopírujte.

OAuth klienti

TAS je od verze 5.19 plnohodnotný OAuth 2.1 autorizační server. Pro MCP je podstatný hlavně public klient. Tak se připojuje Claude nebo ChatGPT: každý uživatel schvaluje přístup sám za sebe a nástroje pak běží pod jeho vlastními rolemi.

1. Přejděte na Administrace > API Access > OAuth Clients.
2. Klikněte na Create client.
3. Vyplňte Client name.
4. Zvolte Client type:
   • Confidential (integration): server-to-server integrace přihlašující se client secretem jako zvolený systémový uživatel, bez souhlasu uživatele,
   • Public (connected application): aplikace, kterou připojuje uživatel, bez client secretu, přes authorization code a PKCE.
5. U confidential klienta vyberte System user a platnost secretu. U public klienta vyplňte Redirect URIs, jedno URI na řádek.
6. Potvrďte tlačítkem Create client a uložte si Client ID.

Zaregistrované redirect URI se dají zpětně přečíst a opravit v detailu klienta. Překlep v callbacku tedy neznamená zakládat klienta znovu.

U confidential klienta se při vytvoření zobrazí i client secret, stejně jednorázově jako API token. Pokud vyprší nebo unikne, nahradíte ho akcí Generate new secret na řádku klienta, aniž by klient přišel o svou identitu a aniž by bylo nutné přenastavovat připojenou aplikaci na nové Client ID.

Souhlas uživatele

Když public klient pošle uživatele na /oauth/authorize, TAS ho nejprve přihlásí kteroukoli nakonfigurovanou autoritou a poté zobrazí souhlasovou obrazovku. Ta jmenuje aplikaci, účet, pod kterým bude jednat, i cíl přesměrování.

Po potvrzení tlačítkem Allow vymění klient jednorázový kód s platností 60 sekund za access token (8 hodin) a rotující refresh token. Access token se na endpointu /mcp chová stejně jako API token.

Dynamická registrace klientů

Aplikace jako Claude se běžně registrují samy přes dynamickou registraci (POST /oauth/register). V TAS je tato možnost ve výchozím stavu vypnutá. Dokud ji nezapnete, je nutné public klienta založit ručně podle postupu výše.

Přepínač najdete v Administrace > Configuration > Application > Authentication pod klíčem application.authentication.oauthDynamicClientRegistration. Změna platí okamžitě, bez restartu.

Ve stejné sekci konfigurace se nastavuje i životnost tokenů: application.authentication.accessExpire (výchozí 28800 sekund, tedy 8 hodin) a application.authentication.refreshExpire (výchozí 2592000 sekund, tedy 30 dní). Samostatný konfigurační blok pro OAuth neexistuje.

Přehled udělených souhlasů

Záložka OAuth Grants ukazuje administrátorovi všechny vydané souhlasy: klienta, uživatele, datum vzniku, poslední použití a platnost. Odvolání souhlasu odpojí jednu aplikaci u jednoho uživatele.

Tentýž seznam, omezený na vlastní připojení, vidí uživatel v Nastavení uživatele > Connected applications. Svoje připojení si může odvolat sám, bez zásahu administrátora.

Scénáře: zúžení katalogu nástrojů

Holé /mcp vystaví všech 35 nástrojů. To je pro většinu úloh zbytečně široký katalog, ve kterém model hůř vybírá a plýtvá kontextem. Volitelný segment cesty vybere pojmenovaný výřez kolekcí a zároveň změní instrukce, které server o sobě klientovi sděluje.

Scénář se promítne i do identity serveru. Endpoint /mcp/knowledge se představí jako tas-mcp-knowledge s instrukcí Answer questions from organization AI documents and TAS product documentation, takže klient rovnou ví, k čemu má server použít.

Neznámý scénář je odmítnut validací ještě před MCP vrstvou, takže odpověď je běžná chyba TAS, ne JSON-RPC chyba:

{"error":{"message":"params/scenario must be equal to one of the allowed values",
  "error":"Bad Request","status":400,"statusCode":400}}

Katalog nástrojů

Nástroje se vystavují pod holým názvem bez prefixu. Kolekce, ze které pocházejí, je uvedena na začátku popisu v hranatých závorkách, například [UserRolesTools] .... Anotace readOnlyHint a destructiveHint se odvozují z druhu nástroje.

Ukázka volání nástroje

curl -s -X POST https://<instance>/api/mcp/account \
  -H "Authorization: Bearer $TAS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call",
       "params":{"name":"query_user_roles","arguments":{}}}'

{"result":{"content":[{"type":"text","text":"{ \"items\": [ ... ] }"}],
  "structuredContent":{"result":{"items":[
    {"ROLE_ID":-1,"ROLE_NAME":"$Administrator","ROLE_CATEGORY":"System", ...},
    {"ROLE_ID":-8,"ROLE_NAME":"$AllUsers", ...}],
    "limit":100,"hasMore":false,"nextCursor":null}}}

Chyba nástroje se nevrací jako JSON-RPC chyba, ale jako výsledek s příznakem isError: true a textovým popisem, aby na ni model mohl reagovat.

Připojení klientů

Bez ohledu na klienta musí každý požadavek nést tyto hlavičky:

• Accept: application/json, text/event-stream (obě hodnoty zároveň),
• Content-Type: application/json,
• Authorization: Bearer <token>.

Hlavička MCP-Protocol-Version je volitelná. Pokud ji klient pošle, musí obsahovat podporovanou hodnotu.

Claude Code

Claude Code umí HTTP transport nativně, token se předá v hlavičce:

claude mcp add --transport http tas \
  https://<instance>/api/mcp/case-lookup \
  --header "Authorization: Bearer $TAS_TOKEN"

Kontrola registrovaných serverů:

claude mcp list

Claude Desktop

Claude Desktop komunikuje přes stdio, HTTP endpoint proto zprostředkuje nástroj mcp-remote. Do souboru claude_desktop_config.json doplňte:

{
  "mcpServers": {
    "tas": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://<instance>/api/mcp/case-creation",
        "--header", "Authorization: Bearer ${TAS_TOKEN}"
      ],
      "env": { "TAS_TOKEN": "eyJhbGciOi..." }
    }
  }
}

claude.ai (vlastní konektor)

V nastavení konektorů stačí vložit adresu https://<instance>/api/mcp. Claude si stáhne discovery dokumenty, zaregistruje se a pošle uživatele na souhlasovou obrazovku TAS.

MCP Inspector

Pro ladění a prohlédnutí katalogu nástrojů:

npx @modelcontextprotocol/inspector

V Inspectoru zvolte transport Streamable HTTP, vložte adresu endpointu a do hlaviček doplňte Authorization: Bearer <token>.

Oprávnění a omezení

Pouze programový token

Endpoint přijímá výhradně token typu api nebo oauth. Běžný session token z prohlížeče je odmítnut jako UNAUTHORIZED, MCP tedy nelze volat z přihlášené relace uživatele. Neautentizovaný požadavek dostane 401 a s ním výzvu, podle které se OAuth klient dostane k discovery:

www-authenticate: Bearer resource_metadata=
  "https://<instance>/api/.well-known/oauth-protected-resource/mcp"

Oprávnění jsou role uživatele

Nástroj běží v uživatelské relaci uživatele, kterému token patří, a vidí přesně to, co by viděl on sám v aplikaci. Role se vyhodnocují v okamžiku volání, ne při vydání tokenu. U public OAuth klienta jde o konkrétního člověka, který udělil souhlas, u API tokenu a confidential klienta o spárovaného systémového uživatele.

Zápisové nástroje se provedou ihned

Rychlost odvolání přístupu

Zneplatněný API token přestane platit okamžitě. U OAuth se platnost grantu ověřuje proti databázi v krátkém intervalu, řádově do minuty. Odvolání souhlasu, zakázání klienta i detekce znovupoužitého refresh tokenu proto odříznou všechny vydané access tokeny v tomto okně, ne až jejich vypršením.

Bez timeoutu na straně serveru

Server nemá vlastní timeout odpovědi. Zrušení nebo časový limit je záměrně ponechán na MCP klientovi.

Audit volání

Každé volání nástroje se zapisuje do tabulky AI_LLM_TOOL_CALL s příznakem zdroje mcp, spolu s uživatelem a kolekcí. Úspěšný záznam vzniká uvnitř téže transakce jako práce nástroje, takže projde buď obojí, nebo nic. Neúspěšný záznam se zapisuje mimo transakci, aby informace o selhání zůstala i po jejím odvolání.

Záznamy se prohlížejí v Administrace > AI monitoring > LLM Tool Calls (/administration/ai-observability/llm-tool-calls).

Odebrání přístupu

Řešení potíží