Tmavý režim
MCP konektor (Claude, ChatGPT)
Každá instance aplikace může mít vlastní MCP konektor: adresu, kterou uživatel vloží do Claude nebo ChatGPT a tím jim zpřístupní aplikaci. AI pak smí jen to, co smí přihlášený uživatel. Vše je řešeno centrálně v user-api — aplikace samotné nemusí implementovat OAuth ani MCP.
Claude / ChatGPT ──OAuth 2.1 + MCP──▶ user-api /mcp/<connector> ──RS256 JWT (60 s)──▶ backend aplikace
│ ověří token, instanci,
│ přístup a oprávnění nástroje
▼
vestavěné nástroje (profil, oprávnění, podpora, notifikace)Co je zaručeno
| Pravidlo | Jak |
|---|---|
| Nic není vystaveno, dokud to admin nezapne | Konektor je vypnutý; nástroj musí být výslovně v allowlistu instance. |
| AI smí jen to, co uživatel | Každý nástroj deklaruje oprávnění; kontrola při tools/list i při každém tools/call (CheckService, cache 30 s). |
| Odebrání práv platí hned | Bezstavový server: přístup k instanci i oprávnění se ověřuje u každého požadavku. |
| Token nejde použít jinde | Token je vázán na jednu instanci (RFC 8707 resource); jiný konektor ho odmítne. |
| Režim jen pro čtení | Nástroje s readOnly: false se v read-only konektoru nikdy nezobrazí. |
| Krádež tokenu | Tokeny jsou v DB jen jako SHA-256; refresh tokeny rotují, opakované použití po 60 s odvolá celé připojení. |
| Audit | Každé volání nástroje je v auditním logu (resource_type = mcp_tool). |
| Odpojení | Uživatel v nastavení aplikace, admin v panelu, vypnutí konektoru odvolá všechna připojení. |
Kdo smí konektor použít
Stejné pravidlo jako brána aplikace — nastavuje se u instance (accessMode):
any_permission(výchozí) — uživatel má v aplikaci aspoň jedno udělené oprávnění,permission— uživatel má konkrétní oprávnění (accessPermission),authenticated— jakýkoli aktivní přihlášený uživatel.
Superadmin a admin aplikace projdou vždy. Deaktivovaný uživatel nikdy.
Nastavení (admin panel)
Aplikace → detail → Instance → AI konektor
- Zapnout konektor, zvolit režim (jen čtení / i změny).
- Volitelně vyplnit URL backendu implementujícího kontrakt.
- Zaškrtnout povolené nástroje. Nové nástroje z backendu jsou vypnuté, dokud je admin nezapne.
- Zkopírovat URL konektoru a předat uživatelům (ti ji vidí i v nastavení aplikace).
Připojení v Claude / ChatGPT
- Claude (claude.ai / Desktop): Settings → Connectors → Add custom connector → vložit URL.
- ChatGPT: Settings → Apps & Connectors → Advanced → Developer mode → Create → URL, autentizace OAuth.
Klient se sám zaregistruje (Dynamic Client Registration), přesměruje na přihlášení přes ZITADEL a uživatel na souhlasové obrazovce vidí aplikaci, svůj účet, cílovou adresu a seznam nástrojů.
Provoz
| Proměnná | Účel |
|---|---|
MCP_STATE_SECRET | HS256 klíč pro stav přihlášení a souhlasu (32+ znaků). Bez něj OAuth neběží. |
MCP_SIGNING_KEY | RSA privátní klíč (base64 PEM) pro podepisování volání backendů. Bez něj fungují jen vestavěné nástroje. |
MCP_PREVIOUS_SIGNING_KEY | Předchozí klíč při rotaci — jen publikován v JWKS. |
mcp.publicBaseUrl | Veřejný origin user-api (issuer, URL konektorů). |
Jednorázově: v aplikaci auth přidat instanci s redirect URI https://<api>/oauth/callback (přihlašovací callback). Admin panel u konektoru vypíše, co chybí.
Caddy musí na hostu user-api propouštět /.well-known/*, /oauth/* a /mcp/*.
Endpointy
| Cesta | Účel |
|---|---|
GET /.well-known/oauth-authorization-server | Metadata autorizačního serveru (RFC 8414) |
GET /.well-known/oauth-protected-resource/mcp/:id | Metadata konektoru (RFC 9728) |
GET /.well-known/jwks.json | Veřejné klíče pro ověření volání backendů |
POST /oauth/register | Dynamic Client Registration (RFC 7591) |
GET /oauth/authorize · POST /oauth/token · POST /oauth/revoke | OAuth 2.1 + PKCE (S256) |
POST /mcp/:id | MCP Streamable HTTP (bezstavový, JSON odpovědi) |
GET/PUT /api/applications/:app/instances/:id/mcp | Nastavení (admin) |
GET /api/applications/:app/instances/:id/mcp/tools | Katalog nástrojů včetně odmítnutých (admin) |
GET/DELETE /api/applications/:app/instances/:id/mcp/grants | Připojení klienti (admin) |
GET /api/mcp/connector?appCode=&origin= | URL a nástroje pro přihlášeného uživatele |
GET/DELETE /api/mcp/connections | Vlastní připojení uživatele |
Test
scripts/e2e-mcp-gate.mjs spustí skutečný server proti dočasné DB a projde celý tok oficiálním MCP SDK klientem (discovery, DCR, PKCE, consent, nástroje, refresh, odvolání, brána).