Konfiguracja MCP w Claude Code: .mcp.json, zakresy i rozwiązywanie problemów

Format pliku .mcp.json

Plik projektowy z jednym serwerem zdalnym i jednym lokalnym wygląda tak:

{
  "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 jest wymagane zawsze, gdy obecne jest url. url bez type jest zgłaszane jako błąd konfiguracji (komunikat mówi, żeby dodać "type": "http", sse albo ws), co zastąpiło starszy i dużo mniej pomocny komunikat o brakującym command. Wartość streamable-http jest akceptowana jako alias dla http. Serwer zdalny wymagający stałego poświadczenia przyjmuje obiekt headers; lokalny przyjmuje command, args i env. Opcjonalne timeout to limit na jedno wywołanie narzędzia, w milisekundach. Serwery WebSocket można zadeklarować tylko w pliku albo przez claude mcp add-json; flaga --transport nie przyjmuje wartości ws.

Polecenie claude mcp add z --scope project zapisuje ten plik za Ciebie, więc ręczna edycja jest potrzebna tylko dla pól, których to polecenie nie udostępnia, albo gdy wolisz przejrzeć zmianę w pull requeście.

Trzymanie sekretów poza plikiem

Ponieważ .mcp.json jest przeznaczony do zatwierdzania w commicie, tokenów nie powinno się wpisywać wprost. Claude Code rozwija zmienne środowiskowe w command, args, env, url i headers: ${VAR} podstawia wartość zmiennej, a ${VAR:-default} zwraca wartość domyślną, gdy zmienna nie jest ustawiona.

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

Przywołana zmienna, która nie jest ustawiona i nie ma wartości domyślnej, nie blokuje wczytania serwera; dosłowny tekst ${API_KEY} jest wysyłany bez zmian, a claude mcp list wypisuje ostrzeżenie. To ostrzeżenie warto sprawdzić w pierwszej kolejności, gdy serwer się łączy, ale każde wywołanie jest odrzucane jako nieautoryzowane.

Dla serwera obsługującego OAuth nie ma nic do ukrywania: zostaw wpis z samym type i url, a każdy użytkownik zaloguje się raz z poziomu /mcp. Token jest przechowywany osobno dla każdego użytkownika, poza repozytorium, i usuwany przez claude mcp remove.

Zatwierdzanie, pierwszeństwo i serwery zarządzane

Gdy Claude Code po raz pierwszy widzi serwer w projektowym .mcp.json, sesja interaktywna pyta, czy go użyć; uruchomienia nieinteraktywne (claude -p, Agent SDK, sesje w chmurze) wczytują go bez pytania. Decyzja jest zapamiętywana per projekt; claude mcp reset-project-choices ją zapomina, dzięki czemu można ponownie zatwierdzić po zmianie.

Gdy jedna nazwa jest zdefiniowana w kilku miejscach, kolejność to: zakres lokalny, potem projektowy, potem użytkownika, potem serwery dostarczane przez wtyczki, a na końcu konektory z claude.ai. Używany jest cały wygrywający wpis. Organizacje mogą narzucić stałą listę serwerów przez zarządzany plik konfiguracji albo ustawienie managedMcpServers (Claude Code 2.1.259 lub nowszy); te mają pierwszeństwo przed każdym zakresem użytkownika, a zarządzany plik żądający wyłącznej kontroli sprawia, że claude mcp add odmawia z komunikatem o aktywnej konfiguracji firmowej. Listy dozwolonych i zabronionych (allowedMcpServers, deniedMcpServers) mogą też ograniczać, jakie adresy URL lub polecenia użytkownicy mogą dodawać, a zakaz zawsze wygrywa.

Odczytywanie statusu

claude mcp list zgłasza każdy serwer jako połączony, wymagający uwierzytelnienia, taki, którego połączenie się nie powiodło, oczekujący na zatwierdzenie, odrzucony przez disabledMcpjsonServers, albo wyłączony dla tego projektu. Warto znać kilka mniej oczywistych ostrzeżeń, jakie wypisuje: ukryte białe znaki na początku lub końcu wartości (wklejony token zakończony znakiem nowej linii), ta sama nazwa wskazująca różne punkty końcowe w dwóch zakresach oraz garstka zastrzeżonych nazw, których nie można użyć dla własnych serwerów. Serwery WebSocket w ogóle nie pojawiają się na tej liście; sprawdzaj je poleceniem claude mcp get <nazwa> albo w /mcp.

Typowe awarie i ich naprawa

1. Serwer zdalny pokazuje "wymaga uwierzytelnienia" albo odpowiada 401 lub 403. Otwórz /mcp, wybierz serwer i dokończ logowanie w przeglądarce, albo uruchom claude mcp login <nazwa>. Jeśli serwer używa stałego tokenu, sprawdź wartość nagłówka i ostrzeżenie o nierozwiniętych zmiennych.
2. Serwer lokalny nie łączy się przy starcie. Uruchom jego polecenie ręcznie w tej samej powłoce, aby zobaczyć rzeczywisty błąd; zwykłe przyczyny to brakujące środowisko uruchomieniowe, pakiet wymagający instalacji albo wymagana zmienna środowiskowa. Wolno startujące serwery trafiają na limit czasu startu, który podnosi MCP_TIMEOUT w milisekundach, na przykład MCP_TIMEOUT=10000 claude.
3. Serwer się łączy, ale narzędzie zwraca obcięty wynik. Wynik narzędzia jest domyślnie ograniczony do 25 000 tokenów, z ostrzeżeniem od 10 000; MAX_MCP_OUTPUT_TOKENS podnosi ten limit.
4. Narzędzia zdają się nie pojawiać w rozmowie. Claude Code odracza definicje narzędzi do chwili, gdy są potrzebne, żeby utrzymać mały kontekst, więc na start wczytują się tylko nazwy i instrukcje serwera; asystent i tak je znajduje, gdy zapytanie do nich pasuje. Ustaw "alwaysLoad": true we wpisie serwera, jeśli chcesz, aby jego pełne definicje były obecne od pierwszej tury.
5. Serwer zdalny odpada w trakcie sesji. Claude Code ponawia zerwane połączenie do pięciu razy z rosnącym opóźnieniem oraz nieudane pierwsze połączenie HTTP do trzech razy, ale nie przy błędach uwierzytelniania i nie dla serwerów lokalnych, więc błąd autoryzacji sam się nie naprawi.

Testowanie konfiguracji na żywym serwisie

Najszybszym sposobem na sprawdzenie projektowego .mcp.json jest serwer, którego odpowiedzi da się zweryfikować niezależnie. Gdy zatwierdzony jest wpis { "type": "http", "url": "https://mcp.host-tracker.com/mcp" }, a każdy programista zalogował się raz przez /mcp, zapytanie w rodzaju "uruchom sprawdzenie HTTP na naszym adresie staging z Europy i Azji" musi wrócić z rzeczywistymi kodami statusu i czasami odpowiedzi z punktów kontrolnych HostTracker, co albo dowodzi poprawnego odczytu pliku, albo zawęża problem do logowania. Powiązany poradnik, jak dodać serwer MCP do Claude Code, opisuje ścieżkę z linii poleceń i zakresy bardziej szczegółowo.