# MCP pro libovolného klienta (https://docs.vitrinka.ai/cs/dev/mcp/clients) Server vitrinka servíruje MCP přes streamable HTTP na `/mcp` (a pro klienty, kteří neumějí poslat hlavičku, per workspace na `/w//mcp`). Vstup mluví OAuth 2.1 (PKCE, dynamická registrace klienta, client-ID metadata documents mimo režim `AIR_GAP=1`, rotující refresh tokeny), takže se každý harness připojí **bez jediného lokálního procesu** — svým standardním záznamem se vzdálenou URL, svým OAuth tokem, svým úložištěm tokenů. Dispatch zůstává na serveru, žádný registrační soubor nikdy nenese přihlašovací údaj a mezi klientem a serverem už nestojí žádný lokální stdio forwarder. ## Jeden grant, jeden endpoint, workspace per repozitář [#levels] * **Jedno přihlášení na origin.** Na souhlasové obrazovce zaškrtnete workspace, které připojení smí používat — výchozí je **Všechny moje workspace, včetně později vytvořených**, napříč všemi organizacemi, do kterých patříte; Personal zůstává soukromý, dokud ho nezaškrtnete. Připojení jedná za vás (jako member) jen tam a jen dokud jste v každém z nich členem. Workspace zvolený jako **výchozí** dostane volání, která žádný workspace nejmenují. Workspace měníte kdykoli v Nastavení → Připojené aplikace — bez nového přihlášení. * **Každý záznam je tentýž endpoint `/mcp`.** **Projektový** záznam, commitnutý v repozitáři, přidává hlavičku `X-Vitrinka-Workspace: `, takže sezení v tom repozitáři přistanou tam; **uživatelský** záznam Claude Code hlavičku nenese a workspace repozitáře přidá ke každému volání hook pluginu vitrinka. Stejná URL, stejný token — při přepnutí repozitáře se znovu nepřihlašujete. * **Volání, které žádný workspace nejmenuje** — z nenavázaného adresáře nebo z hostitele bez hooku — přistane v jediném workspace dosažitelném připojením, který jeho projekt zná, jinak ve výchozím. Projekt, který zná víc vašich workspace, server neuhádne: odmítne volání a vypíše každý zápis `/`. * **Jiný workspace per volání.** Projekt zapište jako `/` (nástěnku `/`, id úkolu, anotace nebo otázky `/` u nástrojů, které berou jen id — id jsou per workspace — nebo předejte `workspace`, který bere každý nástroj) a jednáte v libovolném jiném workspace, na který připojení dosáhne. Volání navázané na workspace, který jeho projekt nemá, dostane zápis workspace, který ho má. Workspace, na který připojení nedosáhne, odpoví `403 workspace_not_connected` se seznamem dosažitelných workspace a odkazem `manage_url`, který ho v Nastavení přidá — nikdy výzvou k přihlášení. Server vynucuje jedno pravidlo pro **uživatelská připojení na kořenovém vstupu**: **přes uživatelské OAuth připojení mohou zápisy mířit jen na projekty, které ve workspace už existují; nový projekt se zakládá ve webovém rozhraní nebo přes workspace vstup `/w//mcp`.** Ani vazba repozitáře, ani hlavička tak sezení nedovolí potichu založit projekt ve workspace, kam volání zrovna přistálo. Výjimku mají připnuté strojové tokeny (servisní a agentní tokeny, vázané na jeden workspace). ## Co renderuje `vitrinka setup` [#install] ```bash vitrinka setup # Claude Code + každý detekovaný harness vitrinka setup --harness cursor,vscode vitrinka setup --harness all ``` Commitnutý `vitrinka.config.json` v kořeni repozitáře (`origins`: origin → workspace, vedle politiky `index`) je jediný manifest; starší `.vitrinka/project.json` se ještě jedno vydání čte a `vitrinka setup` ho do kořenového souboru sloučí. `vitrinka setup`, spuštěný v repozitáři s **explicitní** vazbou, ho vyrenderuje do projektového konfiguračního souboru každého vybraného harnessu: záznam `vitrinka` **sloučí** do existujícího souboru (ostatní servery, neznámé klíče, pořadí klíčů i odsazení přežijí), je idempotentní a nikdy nepřepíše soubor, který nejde přečíst jako čistý JSON — místo toho vytiskne snippet a řekne „upravte ručně“. Repozitář bez vazby nedostane nic (nejdřív navažte: `vitrinka config bind `); výchozí workspace stroje se do commitnutého souboru nikdy nezapeče. Výchozí výběr je Claude Code plus každý harness, jehož domovský adresář nebo CLI je na stroji (`~/.cursor`, `~/.config/opencode` nebo `opencode`, `code` nebo `~/.vscode`, `~/.gemini`) nebo jehož konfigurační soubor či adresář už v repozitáři existuje. `vitrinka doctor` ukazuje jeden řádek na každý soubor harnessu, který repozitář nese — aktuální, zastaralý nebo chybějící vůči URL, kterou by install zapsal — šedě, když ten harness na tomto stroji není. Soubory commitněte: nesou origin a slug workspace, nic tajného, a každý klon se narodí zaregistrovaný. Přihlaste se jednou na harness a origin vlastním tokem harnessu. Token žije v jeho úložišti; Nastavení → Připojené aplikace ve vitrince každé připojení zobrazí, upraví jeho workspace i výchozí workspace a odpojí ho. Commitnuté soubory zapisují URL jako `${VITRINKA_URL:-https://app.vitrinka.ai}/mcp`, takže self-hosted vývojář jednou exportuje `VITRINKA_URL` a tentýž soubor ho následuje; uživatelské záznamy Claude Code a Codexu nesou doslovný origin. ## Claude Code [#claude] Jeden uživatelský záznam v `~/.claude.json` a v repozitáři nic: ```bash claude mcp add --scope user --transport http vitrinka "https://app.vitrinka.ai/mcp?modules=core,pm,me,qa" # ?modules= jmenuje moduly pluginů, které jste nainstalovali — skládá ho vitrinka setup; holé /mcp vypíše všechny moduly kromě rare ``` Přihlaste se jednou: `/mcp` → vitrinka → authenticate (nebo `claude mcp login vitrinka`; na stroji bez prohlížeče `--no-browser`). Jedno připojení obslouží každý zaškrtnutý workspace a Claude Code ukládá token k záznamu, ne k URL — projektový záznam v `.mcp.json`, i se stejnou URL, by tedy stál samostatné přihlášení v každém repozitáři. Žádný proto není: vazba repozitáře žije ve `vitrinka.config.json` a PreToolUse hook pluginu vitrinka (`vitrinka hook-context bind`) ji čte v aktuálním adresáři sezení — včetně worktree a subagentů — a ke každému volání vitrinky, které žádný workspace nejmenuje, přidá `workspace: ""`. Libovolný projekt toho workspace, board nebo holé id pak žádný zápis nepotřebují a dvě sezení v různě navázaných repozitářích přistanou každé ve svém. Volání, které workspace už jmenuje (`workspace`, `/`, `/`, URL úkolu), hook nechá být; nenavázaný repozitář nechá na serveru; nečitelný `vitrinka.config.json` volání odmítne a pojmenuje soubor k opravě. Přepis nenese žádné vlastní schválení: volání dál posuzují pravidla oprávnění Claude Code. `vitrinka doctor` pozůstalý projektový záznam pojmenuje a `vitrinka setup` ho odstraní (`claude mcp remove --scope project vitrinka`). ## Cursor [#cursor] `.cursor/mcp.json` (projekt) — Cursor spustí svůj OAuth tok při prvním použití: ```json { "mcpServers": { "vitrinka": { "url": "${VITRINKA_URL:-https://app.vitrinka.ai}/mcp", "headers": { "X-Vitrinka-Workspace": "" } } } } ``` Uživatelská záloha je tentýž záznam s kořenovým `/mcp` v `~/.cursor/mcp.json`. ## OpenCode [#opencode] `opencode.json` v kořeni repozitáře: ```json { "mcp": { "vitrinka": { "type": "remote", "url": "${VITRINKA_URL:-https://app.vitrinka.ai}/mcp", "enabled": true, "headers": { "X-Vitrinka-Workspace": "" } } } } ``` Repozitář s `opencode.jsonc` se nepřepisuje — install tento blok vytiskne k ručnímu vložení. Uživatelská úroveň: tentýž blok v `~/.config/opencode/opencode.json` s kořenovým `/mcp`. ## VS Code / Copilot [#vscode] `.vscode/mcp.json`: ```json { "servers": { "vitrinka": { "type": "http", "url": "${VITRINKA_URL:-https://app.vitrinka.ai}/mcp", "headers": { "X-Vitrinka-Workspace": "" } } } } ``` VS Code vyzve k OAuth přihlášení při prvním startu serveru. Uživatelská úroveň: **MCP: Open User Configuration** s kořenovým `/mcp`. ## Gemini CLI [#gemini] `.gemini/settings.json`: ```json { "mcpServers": { "vitrinka": { "httpUrl": "${VITRINKA_URL:-https://app.vitrinka.ai}/mcp", "headers": { "X-Vitrinka-Workspace": "" } } } } ``` Uživatelská úroveň: tentýž záznam v `~/.gemini/settings.json` bez hlavičky. ## Codex [#codex] Codex má JEDEN globální registr (`~/.codex/config.toml`), takže `vitrinka setup` tam registruje kořenový vstup a Codex se přihlásí vlastním OAuth tokem: ```bash codex mcp add vitrinka --url https://app.vitrinka.ai/mcp codex mcp login vitrinka ``` `vitrinka setup` přidá i PreToolUse hook do `~/.codex/hooks.json` (jednou mu důvěřujte v `/hooks`): v navázaném repozitáři odmítne volání vitrinky bez workspace a sezení řekne, jaký `workspace` přidat. Codex přijme přepsané volání jen spolu se schválením, proto hook nikdy nepřepisuje. Jiný workspace je na dosah jako `/`. ## Jakýkoli jiný MCP host [#any-host] Hostitelé s podporou OAuth (Claude Desktop, ChatGPT, …) berou tutéž URL. Hostitel, který neumí poslat hlavičku, registruje místo toho vstup workspace `https://app.vitrinka.ai/w//mcp` — tentýž grant, workspace přečtený z cesty. Hostitel, který umí jen spouštět stdio servery, podporovaný není: forwarder byl vyřazen spolu s grantem na celou organizaci. Dvě starší registrace jsou vyřazené: HTTP tvar s hlavičkou `Authorization` (zapékal doslovný přihlašovací údaj do konfiguračních souborů, včetně commitovaných) a stdio forwarder `{ "command": "vitrinka", "args": ["mcp"] }`. `vitrinka doctor` obojí odhalí a `vitrinka setup` to přepíše. Záznamy s `/w//mcp` dál fungují a neoznačují se. ## Katalog, který připojení vidí [#catalogue] Nástroje pojmenované `_` se nevypisují a volání starým jménem odpoví přejmenováním: místo toho volejte generické sloveso s druhem — `list {kind: "work", board}`, `get {kind: "questions", board}` — a kontrakt druhu si přečtěte přes `docs {topic: "kind:"}`. Registrace může zúžit, co se vypíše: připojte ke své URL `?modules=core,pm`; core je vždy uvnitř. Málo používané dveře — `board_working`, `save_template`, `review_judge`, přesun a sloučení projektů, oblíbené — sedí v modulu `rare` a vypíšou se jen tehdy, když ho registrace jmenuje; živé párování třeba potřebuje `board_working`. Jakmile moduly vyjmenujete, vypíšou se jen ty, takže uveďte každý, o který nechcete přijít: `…/mcp?modules=core,pm,qa,me,rare`. `vitrinka setup` tuto volbu drží: takový záznam nechá být, a když registraci přepisuje — jiný origin, nové navázání, vyřazený tvar — přenese `?modules=` do nové URL, s výjimkou záznamu v projektovém `.mcp.json`, který odstraní i s jeho moduly. Jakýkoli jiný query parametr nebo hodnota s čímkoli jiným než názvy modulů, čárkami a %-escapy se čte jako zastaralá a přepíše se na holé dveře. Řádek **MCP catalogue** ve `vitrinka doctor` spočítá, co vypisuje váš záznam v Claude Code. Host, který setup nespravuje, může moduly poslat místo toho v hlavičce `X-Vitrinka-Modules`; záznam spravovaný setupem, který tu hlavičku nese, se čte jako zastaralý a přepíše se bez ní. Zúžení jen ztenčí výpis, nikdy neuděluje ani neodebírá oprávnění — nemění, co token smí. ## Naslouchání [#listening] Nástěnka je živá jen dokud je na ni naladěné sezení: anotace a odeslané odpovědi se k agentovi dostávají přes `vitrinka work watch`, pronajatý long-poll, který vytiskne jeden řádek na položku práce. Co z toho řádku udělá probuzené sezení, závisí na harnessu — žebřík skillu listen vybere nejvyšší dostupnou příčku a jednou ji ohlásí, a indikátor naslouchání na nástěnce ukazuje harness i příčku, které dostal z pronájmu. | Harness | Jak naslouchá | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Claude Code | Nativní `Monitor` na pozadí nad `exec vitrinka work watch --keepalive 0` — řádek sezení znovu vyvolá, nečinnost nic nestojí. | | Codex, Gemini CLI, OpenCode | `vitrinka work listen --harness ` hostuje harness přes Agent Client Protocol a každou položku práce vloží do živého sezení jako prompt; `vitrinka work watch --exec ` pro vyhrazeného posluchače obnovuje vlákno bez obrazovky. Bez hosta načte práci jednou a při nečinnosti ukončí tah. | | Cursor, VS Code | Načte práci jednou a při nečinnosti ukončí tah; průběžné doručování vyžaduje kompatibilního hosta na pozadí. Model nesmí udržovat tah opakovanými dotazy na prázdnou frontu. | ```bash vitrinka work listen --harness codex # hostuje Codex; práce přichází jako prompty vitrinka work listen --harness gemini --board acme-audit vitrinka work watch --exec codex # bez obrazovky: obnoví naslouchající vlákno pro každou položku ``` `vitrinka setup` nainstaluje ACP adaptér vybraného harnessu a `vitrinka doctor` hlásí pro každý harness jeden řádek `listen·` a `acp·`, takže stroj, který umí naslouchat jen na nejslabší příčce, to řekne dřív, než nástěnka ztichne. Rozsah drží vždy jen jeden živý posluchač — nastražení z jiného sezení na témže stroji ho převezme; sezení na jiném stroji se nikdy nevytlačí. ## Čtení velkých odpovědí [#read-budgets] Výchozí odpovědi MCP určené pouze ke čtení vracejí nad přibližně 2 000 odhadovaných textových tokenů označené shrnutí s postupem pro rozbalení. Pro úplný nebo cílený obsah předejte výslovně `budget`, `select` nebo `jq`; nadále platí výchozí ochranný limit 8 000 tokenů a výslovné maximum 30 000. Odpovědi na změny se automaticky neshrnují. Odpověď aktivního `wait_for_work` zachová již převzaté volby, dotazy a oznámení sezení celé, i nad limitem (projekce `select`/`jq` se stále uplatní): tyto události už byly označeny jako doručené. Prázdná odpověď naopak uvádí `action: "end_turn"` a `retry: false`; třetí prázdný dotaz během dvou minut dostane upozornění `idle_poll_loop`. ## Skilly [#skills] Skilly se šíří odděleně od MCP, jako pluginy `vitrinka@kit`, `vitrinka-pm@kit`, `vitrinka-qa@kit` a volitelný `vitrinka-experimental@kit` z marketplace `henderson-tech/vitrinka-kit` — i to zařídí `vitrinka setup` a z nainstalovaných pluginů složí `?modules=` registrace. Viz [přehled skillů](/cs/dev/skills/overview).