MCP pro libovolného klienta

Server vitrinka servíruje MCP přes streamable HTTP na /mcp (a pro klienty, kteří neumějí poslat hlavičku, per workspace na /w/<workspace>/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ář

• 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: <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 <workspace>/<project>.
• Jiný workspace per volání. Projekt zapište jako <workspace>/<project> (nástěnku <workspace>/<slug>, id úkolu, anotace nebo otázky <workspace>/<id> 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/<workspace>/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

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 <workspace>); 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

Jeden uživatelský záznam v ~/.claude.json a v repozitáři nic:

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: "<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, <workspace>/<project>, <workspace>/<id>, 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/mcp.json (projekt) — Cursor spustí svůj OAuth tok při prvním použití:

{
  "mcpServers": {
    "vitrinka": { "url": "${VITRINKA_URL:-https://app.vitrinka.ai}/mcp", "headers": { "X-Vitrinka-Workspace": "<workspace>" } }
  }
}

Uživatelská záloha je tentýž záznam s kořenovým /mcp v ~/.cursor/mcp.json.

OpenCode

opencode.json v kořeni repozitáře:

{
  "mcp": {
    "vitrinka": { "type": "remote", "url": "${VITRINKA_URL:-https://app.vitrinka.ai}/mcp", "enabled": true, "headers": { "X-Vitrinka-Workspace": "<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/mcp.json:

{
  "servers": {
    "vitrinka": { "type": "http", "url": "${VITRINKA_URL:-https://app.vitrinka.ai}/mcp", "headers": { "X-Vitrinka-Workspace": "<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/settings.json:

{
  "mcpServers": {
    "vitrinka": { "httpUrl": "${VITRINKA_URL:-https://app.vitrinka.ai}/mcp", "headers": { "X-Vitrinka-Workspace": "<workspace>" } }
  }
}

Uživatelská úroveň: tentýž záznam v ~/.gemini/settings.json bez hlavičky.

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:

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 <workspace>/<project>.

Jakýkoli jiný MCP 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/<workspace>/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.

Katalog, který připojení vidí

Nástroje pojmenované <verb>_<kind> 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:<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í

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.

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·<harness> a acp·<harness>, 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í

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

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ů.