Konfigurace MCP v Claude Code: .mcp.json, rozsahy a řešení potíží

Formát .mcp.json

Projektový soubor s jedním vzdáleným a jedním lokálním serverem vypadá takto:

{
  "mcpServers": {
    "hosttracker": {
      "type": "http",
      "url": "https://mcp.host-tracker.com/mcp"
    },
    "local-tool": {
      "type": "stdio",
      "command": "/path/to/executable",
      "args": ["--flag", "value"],
      "env": { "KEY": "value" },
      "timeout": 600000
    }
  }
}

Pole type je povinné vždy, když je přítomné url. url bez type se hlásí jako chyba konfigurace (zpráva vás vyzve přidat "type": "http", případně sse nebo ws), což nahradilo starší a mnohem méně srozumitelné hlášení o chybějícím command. Hodnota streamable-http je přijímána jako alias pro http. Vzdálený server, který potřebuje pevné přihlašovací údaje, má objekt headers; lokální má command, args a env. Volitelný timeout je limit na jedno volání nástroje v milisekundách. Servery WebSocket lze deklarovat jen v souboru nebo přes claude mcp add-json; přepínač --transport hodnotu ws nepřijímá.

Příkaz claude mcp add s --scope project tento soubor zapíše za vás, takže ruční úpravy jsou potřeba jen pro pole, která příkaz nenabízí, nebo když chcete změnu projít v pull requestu.

Jak z souboru vynechat tajné údaje

Protože .mcp.json je určený k commitnutí, tokeny by se do něj neměly psát přímo. Claude Code rozbaluje proměnné prostředí v command, args, env, url a headers: ${VAR} vezme hodnotu proměnné a ${VAR:-default} se vrátí k výchozí hodnotě, když proměnná není nastavená.

{
  "mcpServers": {
    "secure-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

Odkazovaná proměnná, která není nastavená a nemá výchozí hodnotu, načtení serveru nezastaví; doslovný text ${API_KEY} se odešle tak, jak je, a claude mcp list vypíše varování. Toto varování je první věc, kterou hledat, když se server připojí, ale každé volání skončí jako neautorizované.

U serveru, který podporuje OAuth, není co skrývat vůbec: ponechte položku jen s type a url, a každý uživatel se jednou přihlásí z /mcp. Token se ukládá pro každého uživatele zvlášť, mimo repozitář, a claude mcp remove ho zase odstraní.

Schválení, priorita a spravované servery

Když Claude Code poprvé uvidí server v projektovém .mcp.json, interaktivní relace se zeptá, zda ho použít; neinteraktivní běhy (claude -p, Agent SDK, cloudové relace) ho načtou bez ptaní. Rozhodnutí se pamatuje pro daný projekt; claude mcp reset-project-choices ho zapomene, abyste mohli po změně znovu schválit.

Když je jeden název definovaný na více místech, pořadí je lokální rozsah, poté projektový, poté uživatelský, poté servery poskytnuté pluginy, a nakonec konektory z claude.ai. Použije se celá vítězná položka. Organizace mohou vynutit pevný seznam serverů přes spravovaný konfigurační soubor nebo nastavení managedMcpServers (Claude Code 2.1.259 nebo novější); ty mají přednost před každým rozsahem na úrovni uživatele, a spravovaný soubor, který si nárokuje výhradní kontrolu, způsobí, že claude mcp add odmítne s hlášením, že je aktivní firemní konfigurace. Seznamy povolených a zakázaných serverů (allowedMcpServers, deniedMcpServers) mohou také omezit, které URL nebo příkazy smí uživatelé přidávat, a zákaz má vždy přednost.

Jak číst výstup stavu

claude mcp list hlásí každý server jako connected, needs authentication, failed to connect, pending approval, rejected přes disabledMcpjsonServers, nebo disabled pro tento projekt. Stojí za to znát i pár méně zjevných varování, která vypisuje: skryté mezery na začátku nebo konci hodnoty (vložený token, který skončil novým řádkem), stejný název odkazující na jiný endpoint ve dvou rozsazích, a pár rezervovaných názvů, které nelze použít pro vlastní servery. Servery WebSocket se v seznamu vůbec nezobrazují; zkontrolujte je příkazem claude mcp get <name> nebo přes /mcp.

Časté chyby a jejich řešení

1. Vzdálený server ukazuje "needs authentication" nebo odpovídá 401 či 403. Otevřete /mcp, vyberte server a dokončete přihlášení v prohlížeči, nebo spusťte claude mcp login <name>. Pokud server používá statický token, zkontrolujte hodnotu hlavičky a varování o nerozbalených proměnných.
2. Lokální server se při startu nepřipojí. Spusťte jeho příkaz ručně ve stejném shellu, abyste viděli skutečnou chybu; obvyklou příčinou je chybějící runtime, balíček, který je potřeba nainstalovat, nebo požadovaná proměnná prostředí. Pomalu startující servery narazí na limit pro spuštění, který zvyšuje MCP_TIMEOUT v milisekundách, například MCP_TIMEOUT=10000 claude.
3. Server se připojí, ale nástroj vrátí zkrácený výsledek. Výstup nástroje je ve výchozím stavu omezen na 25 000 tokenů, s varováním od 10 000; MAX_MCP_OUTPUT_TOKENS tento limit zvyšuje.
4. Zdá se, že v konverzaci nástroje chybí. Claude Code odkládá definice nástrojů, dokud nejsou potřeba, aby udržel kontext malý, takže na začátku se načtou jen názvy a instrukce serveru; asistent je stejně najde, jakmile požadavek odpovídá. Nastavte "alwaysLoad": true u položky serveru, pokud chcete mít jeho úplné definice k dispozici už od prvního tahu.
5. Vzdálený server během relace vypadne. Claude Code opakuje přerušené spojení až pětkrát s rostoucím zpožděním a neúspěšné první HTTP spojení až třikrát, ale ne u chyb autentizace a ne u lokálních serverů, takže chyba přihlášení se sama neopraví.

Testování konfigurace proti živé službě

Nejrychlejší způsob, jak ověřit projektový .mcp.json, je server, jehož odpovědi umíte nezávisle zkontrolovat. S commitnutým { "type": "http", "url": "https://mcp.host-tracker.com/mcp" } a každým vývojářem jednou přihlášeným přes /mcp musí požadavek typu "spusť HTTP kontrolu na naší staging URL z Evropy a Asie" vrátit skutečné stavové kódy a doby odezvy z kontrolních bodů HostTracker, což buď potvrdí, že se soubor čte správně, nebo zúží chybu na přihlášení. Doplňkový návod jak přidat MCP server do Claude Code popisuje cestu přes příkazovou řádku a rozsahy podrobněji.