Konfiguracja serwerów MCP w Codexie

Codex łączy się z serwerami MCP (Model Context Protocol) zadeklarowanymi jako tabele [mcp_servers.<nazwa>] w config.toml: z serwerami stdio, które Codex uruchamia jako lokalny proces, oraz z serwerami streamable HTTP dostępnymi pod adresem URL, z tokenem bearer albo OAuth. Polecenie codex mcp dodaje, sprawdza i uwierzytelnia serwery, a każdy serwer powinien przejść test dymny, zanim jego wynikom się zaufa.

Ta strona jest dla programisty, który konfiguruje Codexa na własnej maszynie, i dla tech leada, który chce mieć te same serwery u każdego w zespole. Prosisz Codexa o naprawienie najczęstszego błędu z Sentry, a on odpowiada, że nie ma dostępu do zewnętrznych serwisów. Prosisz o middleware w Next.js i dostajesz API sprzed dwóch wersji głównych. W obu przypadkach brakuje kontekstu, a podłączenie właściwego serwera MCP to jedno polecenie. Więcej czasu zajmuje co innego: ograniczenie tego, co serwer może robić, i udowodnienie, że naprawdę zadziałał.

Co zyskujesz dzięki konfiguracji MCP w Codexie

• Pierwszy działający serwer (Context7), sprawdzony przez codex mcp list, /mcp i skryptowy test dymny.
• Gotową konfigurację pięciu serwerów, od których zaczyna większość zespołów: Context7, Playwright, GitHub, Figma i Sentry.
• Listy dozwolonych narzędzi, tryby zatwierdzania i limity wyjścia osobno dla każdego serwera, żeby serwer nie zalał kontekstu ani niczego nie zapisał bez pytania.
• Sekrety w zmiennych środowiskowych, a nie w pliku, który trafia do repozytorium.
• Sprawdzenie w codex exec, które zatrzymuje CI, gdy wymagany serwer nie wystartuje.

Zanim zaczniesz, przejdź przez konfigurację Codexa: ta strona zakłada działający ~/.codex/config.toml i zalogowane Codex CLI (sprawdzone na codex-cli 0.157.1; podpolecenia codex mcp i flagi użyte na tej stronie sprawdzono ponownie na 0.162.1 dnia 2026-10-12).

Jak Codex łączy się z serwerem MCP?

Codex obsługuje dwa transporty. O tym, którego używa tabela, decydują ustawione w niej pola, a przy wczytywaniu konfiguracji Codex odrzuca pola należące do drugiego transportu.

Transport	Codex uruchamia go przez	Wymagany klucz	Uwierzytelnianie	Typowe serwery
stdio	Uruchomienie command z args jako procesu potomnego	command	env_vars przekazywane z twojej powłoki, env	Context7 (npm), Playwright, Chrome DevTools, lokalny GitHub w Dockerze
Streamable HTTP	Połączenie z url	url	bearer_token_env_var, env_http_headers, OAuth przez codex mcp login	zdalny GitHub, Figma, Sentry, zdalny Context7

Miejsce, w którym leży konfiguracja, ma większe znaczenie, niż się wydaje:

• ~/.codex/config.toml (w CODEX_HOME) to twój plik osobisty. codex mcp add zapisuje tutaj i tylko tutaj (0.157.1). CLI, rozszerzenie IDE i aplikacja desktopowa Codexa czytają go, gdy korzystają z tego samego CODEX_HOME.
• .codex/config.toml w repozytorium to plik zespołu. Codex wczytuje go tylko wtedy, gdy oznaczysz projekt jako zaufany; w niezaufanym repozytorium plik jest wczytany, ale wyłączony.

Codex 0.157.1 wciąż rozmawia z serwerami protokołem MCP sprzed 2026-07-28: obsługa specyfikacji 2026-07-28 jest za flagą mcp_2026_07_28, którą codex features list pokazuje jako „under development” i wyłączoną. Co zmieniło się w specyfikacji, opisuje przegląd MCP.

Dodaj pierwszy serwer i sprawdź, że działa

Context7 to najlepszy pierwszy serwer: nie wymaga konta, a efekt widać po jednym prompcie.

1. Dodaj serwer. Wszystko po -- to polecenie, które uruchomi Codex:

   codex mcp add context7 -- npx -y @upstash/context7-mcp

   Codex wypisuje Added global MCP server 'context7'. i zapisuje w ~/.codex/config.toml taką tabelę:

   [mcp_servers.context7]
   command = "npx"
   args = ["-y", "@upstash/context7-mcp"]

2. Potwierdź, że Codex ją sparsował. codex mcp list pokazuje wszystkie skonfigurowane serwery, a codex mcp get context7 --json wypisuje efektywne ustawienia jednego z nich:

   codex mcp list
   codex mcp get context7 --json

3. Uruchom Codexa i wpisz /mcp w polu wiadomości. Polecenie wyświetla skonfigurowane narzędzia MCP, a /mcp verbose dodaje szczegóły. Jeśli przy context7 nie ma narzędzi, przejdź do sekcji Gdy serwery MCP w Codexie nie działają.

4. Wklej poniższy prompt i sprawdź, czy odpowiedź podaje identyfikator biblioteki Context7.

   Prompt do skopiowania: sprawdź, czy Context7 działa

   Use the context7 MCP server to look up how Next.js middleware redirects an
   unauthenticated request to /login. Before writing any code, tell me the exact
   Context7 library ID and version you resolved, and quote the one doc snippet you
   are relying on. Then write middleware.ts for that version and nothing else.

Prompt celowo prosi o identyfikator biblioteki i cytat z dokumentacji. Odpowiedź bez nich pochodzi z danych treningowych, a nie z serwera, i właśnie ten przypadek chcesz wykluczyć.

Skonfiguruj serwery, od których zaczyna większość zespołów

Każdy blok poniżej to albo polecenie codex mcp add, albo równoważna tabela w config.toml; użyj jednego z nich. Wersje pakietów sprawdzono w npm 2026-09-26: @upstash/context7-mcp 4.1.1 i @playwright/mcp 0.0.82.

Context7

Dokumentacja bibliotek w konkretnej wersji. Klucz API jest opcjonalny i podnosi limity zapytań. Żeby użyć zdalnego serwera z kluczem, odczytaj go ze zmiennej środowiskowej:

[mcp_servers.context7]
url = "https://mcp.context7.com/mcp"
bearer_token_env_var = "CONTEXT7_API_KEY"

Więcej promptów i alternatywa oparta na skillach: Context7.

Playwright

Automatyzacja przeglądarki przez drzewo dostępności, do odtwarzania błędów UI i sprawdzania ścieżki po zmianie.

codex mcp add playwright -- npx @playwright/mcp@latest --isolated

--isolated trzyma profil przeglądarki w pamięci. Bez tej flagi dwie sesje Codexa w równoległych worktree walczą o jeden profil. README Playwrighta sugeruje teraz, że agentom kodującym może lepiej służyć jego CLI ze skillami, bo zrzuty drzewa dostępności kosztują kontekst; zobacz Playwright MCP.

GitHub

Oficjalny serwer GitHuba do PR-ów, issues i logów Actions. Zdalny serwer pobiera fine-grained personal access token ze zmiennej środowiskowej:

export GITHUB_PAT_TOKEN=github_pat_...   # in your shell profile, never in config.toml
codex mcp add github --url https://api.githubcopilot.com/mcp/ --bearer-token-env-var GITHUB_PAT_TOKEN

Żeby uruchomić go lokalnie w Dockerze, przekaż zmienną o nazwie, której oczekuje obraz, czyli GITHUB_PERSONAL_ACCESS_TOKEN:

[mcp_servers.github]
command = "docker"
args = ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"]
env_vars = ["GITHUB_PERSONAL_ACCESS_TOKEN"]

Pakiet npm @modelcontextprotocol/server-github jest w npm oznaczony jako przestarzały; nie używaj go. Zawężanie zestawów narzędzi i adresy tylko do odczytu opisuje GitHub MCP.

Figma

Kontekst projektu, zrzuty ekranu i mapowania Code Connect ze zdalnego serwera Figmy, z OAuth:

codex mcp add figma --url https://mcp.figma.com/mcp

Gdy codex mcp add --url wykryje, że serwer obsługuje OAuth, od razu otwiera logowanie w przeglądarce. Jeśli wypisze „may or may not require login”, uruchom codex mcp login figma. Figma ogranicza plan Starter oraz miejsca View i Collab w planach płatnych do „up to 6 tool calls per month” (przewodnik MCP Figmy, odczyt we wrześniu 2026), więc osobie, która zamienia projekty na kod, daj miejsce Dev albo Full. Zobacz Figma i MCP dla design systemów.

Sentry

Issues, zdarzenia i ślady z hostowanego serwera Sentry, z OAuth. Codex obsługuje streamable HTTP natywnie, więc nie potrzebujesz pośrednika mcp-remote:

codex mcp add sentry --url https://mcp.sentry.dev/mcp
codex mcp login sentry   # only if the add step did not start the login

Jeśli uwierzytelniasz się tokenem zamiast OAuth, Sentry oczekuje nagłówka Authorization: Sentry-Bearer <token>, a nie Bearer. Ustaw go przez env_http_headers, jak w sekcji Trzymaj sekrety poza config.toml. Pakiet stdio @sentry/mcp-server (0.42.0) jest przeznaczony dla samodzielnie hostowanego Sentry.

Dodaj serwer, który wymaga wcześniej zarejestrowanego klienta OAuth

Niektóre serwery OAuth dają ci identyfikator klienta i sekret klienta zamiast rejestrować Codexa automatycznie. codex mcp add przyjmuje oba (codex mcp add --help w 0.162.1, sprawdzone 2026-10-12):

read -rs MCP_CLIENT_SECRET   # paste the secret from the server's admin page, then press Enter
codex mcp add my-server --url https://mcp.example.com/mcp \
  --oauth-client-id CLIENT_ID \
  --oauth-client-secret "$MCP_CLIENT_SECRET"

Zastąp CLIENT_ID identyfikatorem, który wydał serwer. read -rs pobiera sekret bez wyświetlania go, więc nie trafia on do historii powłoki. --oauth-client-secret nadal przyjmuje wartość jako argument wiersza poleceń (codex mcp add --help), więc inne procesy na maszynie widzą go na liście procesów, dopóki polecenie działa. Flaga pojawiła się w 0.158.0 (2026-09-28); notatki do wydania opisują je jako przeznaczone dla wcześniej zarejestrowanych klientów OAuth. Ta sama pomoc wymienia --oauth-client-registration (auto, cimd lub dcr, tylko dla natychmiastowego logowania) i --oauth-resource (parametr zasobu OAuth dla tego logowania).

Aby uwierzytelnić się ponownie później, uruchom w terminalu codex mcp login NAZWA, które przyjmuje też --no-browser, --scopes SCOPE,SCOPE i --oauth-client-registration. W sesji logowanie uruchamia /mcp login <name> (0.161.0, 2026-10-07); lista poleceń 0.162.1 opisuje /mcp jako list MCP tools; use /mcp verbose or /mcp login <name>.

Ogranicz, co może robić każdy serwer

Każdy dodany serwer daje modelowi dostęp do swoich narzędzi. Od wersji 0.143.0 (2026-07-08) Codex domyślnie wyszukuje narzędzia MCP na żądanie, więc nieużywany serwer kosztuje niewiele. Wynik narzędzia trafia jednak do kontekstu, a narzędzie zapisujące działa z uprawnieniami swojego tokena. Ogranicz jedno i drugie osobno dla każdego serwera:

[mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
bearer_token_env_var = "GITHUB_PAT_TOKEN"
enabled_tools = ["pull_request_read", "actions_list", "get_job_logs", "create_pull_request"]
default_tools_approval_mode = "prompt"   # ask before every tool call from this server
startup_timeout_sec = 30                 # default 30
tool_timeout_sec = 120                   # default 300

[mcp_servers.github.tools.get_job_logs]
approval_mode = "auto"                   # back to the default: no prompt if the server marks the tool read-only
output_token_limit = 8000                # cap one huge CI log

• enabled_tools to lista dozwolonych narzędzi; disabled_tools usuwa narzędzia już po jej zastosowaniu.

• default_tools_approval_mode ustawia politykę dla całego serwera, a [mcp_servers.<nazwa>.tools.<narzędzie>] nadpisuje ją dla jednego narzędzia. Cztery wartości, tak jak implementuje je codex-rs/core/src/mcp_tool_call.rs w wersji 0.157.1, opierają się na adnotacjach, które serwer publikuje dla każdego narzędzia:

  • auto (domyślna) nie pyta o narzędzia oznaczone przez serwer jako tylko do odczytu, a pyta o narzędzia oznaczone jako destrukcyjne lub open-world albo pozbawione adnotacji.
  • prompt pyta przed każdym wywołaniem.
  • writes pyta przed każdym wywołaniem narzędzia, które nie jest oznaczone jako tylko do odczytu.
  • approve nigdy nie pyta.

  Te wartości działają, gdy Codex może zapytać. Przy approval_policy = "never" (na przykład w nienadzorowanych uruchomieniach codex exec) wywołanie, które wymagałoby pytania, zostaje odrzucone, chyba że sandbox ma pełny dostęp; wtedy wykonuje się bez pytania (sprawdzone w 0.157.1). W CI ustaw serwerom, od których zależy zadanie, auto albo jawne approve dla konkretnych narzędzi.

• output_token_limit ogranicza wyjście pojedynczego narzędzia; to ustawienie powstrzymuje zrzut logu przed wypchnięciem twojego zadania z kontekstu. Szerszy kompromis opisuje ograniczanie kosztu tokenów MCP.

• enabled = false wyłącza serwer bez usuwania tabeli. codex mcp remove <nazwa> ją usuwa.

Nazwy narzędzi różnią się między serwerami i wersjami. Zanim napiszesz listę dozwolonych narzędzi, odczytaj prawdziwe nazwy z /mcp verbose, bo literówka po cichu usuwa narzędzie.

Trzymaj sekrety poza config.toml

Codex daje trzy sposoby przekazania sekretu bez wpisywania go do pliku:

# stdio: forward named variables from your shell to the server process
[mcp_servers.github_local]
command = "docker"
args = ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"]
env_vars = ["GITHUB_PERSONAL_ACCESS_TOKEN"]

# HTTP: send the value of an env var as `Authorization: Bearer <value>`
[mcp_servers.context7]
url = "https://mcp.context7.com/mcp"
bearer_token_env_var = "CONTEXT7_API_KEY"

# HTTP: any header, filled from an env var (here SENTRY_AUTH_HEADER="Sentry-Bearer sntrys_...")
[mcp_servers.sentry_token]
url = "https://mcp.sentry.dev/mcp"
env_http_headers = { "Authorization" = "SENTRY_AUTH_HEADER" }

Trzy rzeczy, których należy unikać. codex mcp add --env KLUCZ=WARTOŚĆ zapisuje samą wartość w config.toml, więc używaj go tylko do ustawień, które nie są tajne. Dosłowny klucz bearer_token jest odrzucany dla serwerów HTTP (0.157.1), więc stare fragmenty konfiguracji, które go ustawiają, nie wczytają się. A dane OAuth z codex mcp login trafiają do systemowego pęku kluczy, jeśli jest dostępny, a w przeciwnym razie do pliku w CODEX_HOME, który trzeba traktować jak klucz prywatny. Zawężanie uprawnień tokenów opisuje zabezpieczanie serwerów MCP.

Jedna konfiguracja MCP dla całego zespołu

W zespole zacommituj serwery potrzebne wszystkim do .codex/config.toml w repozytorium, tylko z nazwami zmiennych środowiskowych, a same zmienne opisz w AGENTS.md albo w README. Każdy programista raz oznacza projekt jako zaufany i eksportuje własne tokeny. Przy migracji pomagają dwa skróty: /import w TUI Codexa przenosi serwery MCP, ustawienia i pluginy z Claude Code i Cursora (od 0.145.0), a codex plugin list pokazuje pluginy dostawców, które łączą konfigurację serwera ze skillami.

Notatka

We wszystkich trzech narzędziach idea konfiguracji jest ta sama, ale pliki są inne: Claude Code używa .mcp.json i claude mcp add, a Cursor mcp.json. Pakiety serwerów i adresy URL są identyczne. Zobacz konfigurację MCP w Claude Code i konfigurację MCP w Cursorze.

Jak sprawdzić pracę opartą na MCP bez czytania każdej linii?

Serwer MCP zmienia to, co agent wie, a nie sposób, w jaki sprawdzasz wynik. Zweryfikuj trzy rzeczy, w tej kolejności.

1. Serwer działa. W przebiegach bez nadzoru oznacz serwery, od których zależy zadanie, jako wymagane. Z required = true polecenie codex exec kończy się błędem, gdy serwer nie wystartuje, zamiast pracować dalej bez niego:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
required = true

2. Narzędzie naprawdę zostało wywołane. codex exec --json wypisuje jedno zdarzenie na linię, a każde wywołanie MCP pojawia się jako zdarzenie item.completed, którego element ma type równe mcp_tool_call oraz pola server, tool i status (completed albo failed). Ten test dymny kończy się błędem, gdy żadne wywołanie Context7 się nie powiodło:

codex exec --json --ephemeral \
  "Use the context7 MCP server to resolve the library ID for React. Reply with the ID only." \
  | jq -r 'select(.type=="item.completed" and .item.type=="mcp_tool_call")
           | [.item.server, .item.tool, .item.status] | @tsv' \
  | grep -q $'^context7\t.*\tcompleted$' && echo "context7 OK" || { echo "context7 NOT CALLED"; false; }

Końcowe false oznacza krok CI jako nieudany, ale nie zamyka interaktywnej powłoki. Uruchamiaj go po wdrożeniu nowej osoby, po aktualizacji Codexa i w CI przed każdym zadaniem, które zależy od serwera. codex exec w pipeline’ach opisuje strona Codex bez interakcji.

3. Zmiana jest poprawna. Dokumentacja z Context7 czy stack trace z Sentry nie czynią kodu poprawnym. Bramką nadal są twoje testy, sprawdzanie typów i linter, a do tego test, który nie przechodzi przed poprawką. Poproś o to wprost:

Prompt do skopiowania: od błędu w Sentry do przetestowanej poprawki

Use the sentry MCP server to find the unresolved issue with the most events in
the last 24 hours for project web-frontend. Show me the issue ID, the top three
stack frames, and the local files they map to. Then write a failing test that
reproduces it, make the smallest fix that turns the test green, and run the full
test suite. Do not change code outside the files the stack trace points to.

Prompt do skopiowania: przegląd stanu serwerów MCP

For every MCP server you have access to, call one read-only tool with a trivial
argument. Report a table with columns: server, tool called, result (ok / error),
and the error text if any. Do not call any tool that creates, updates, or deletes
anything.

Recenzent sprawdza wtedy dowody — identyfikator issue, test najpierw czerwony, potem zielony, i przechodzący zestaw testów — zamiast czytać diff linia po linii.

Gdy serwery MCP w Codexie nie działają

Objaw	Prawdopodobna przyczyna	Co zrobić
Po edycji tabeli Codex zgłasza błąd konfiguracji	Klucz z drugiego transportu (na przykład env_vars przy serwerze z url albo dosłowny bearer_token) albo wartość złego typu	Popraw klucz; codex mcp get <nazwa> --json powinno działać bez błędu
Ustawienie nie działa	Literówka albo nieznany klucz, który Codex 0.157.1 po cichu ignoruje (na przykład headers zamiast http_headers)	Klucze transportu (url, bearer_token_env_var, env_http_headers, http_headers), limity czasu i listy narzędzi sprawdź w codex mcp get <nazwa> --json; ten wynik nie pokazuje required, trybów zatwierdzania ani output_token_limit, więc te nazwy porównaj z dokumentacją konfiguracji Codexa
Serwer jest na liście, ale /mcp nie pokazuje narzędzi	Polecenie się nie powiodło: brak npx w PATH, niedziałający Docker, brakująca zmienna	Uruchom dokładnie te command i args w terminalu; wyeksportuj zmienne z env_vars przed uruchomieniem Codexa
„startup timeout” przy pierwszym uruchomieniu	npx albo docker pull pobiera pakiet w ramach domyślnych 30 sekund	Pobierz pakiet raz wcześniej (npx -y @upstash/context7-mcp --help) albo podnieś startup_timeout_sec
Wywołania narzędzi przekraczają czas przy dużych stronach lub logach	Wolne narzędzie, domyślny limit 300 sekund	Podnieś tool_timeout_sec tylko dla tego serwera; ogranicz wyjście przez output_token_limit
Działa w terminalu, ale nie w rozszerzeniu IDE ani w aplikacji	Inne CODEX_HOME albo zmienna wyeksportowana tylko w interaktywnej powłoce	Skieruj oba na jedno CODEX_HOME; eksporty umieść w pliku, który wczytuje też sesja graficzna, i uruchom aplikację ponownie
W świeżym klonie brakuje serwerów zespołu	Projekt nie jest zaufany, więc .codex/config.toml jest wczytany, ale wyłączony	Oznacz projekt jako zaufany, gdy Codex zapyta, i uruchom sesję ponownie
Logowanie OAuth nigdy się nie kończy	Firmowe proxy albo firewall blokuje lokalny callback	Ustaw mcp_oauth_callback_port na dozwolony port albo uruchom codex mcp login <nazwa> --no-browser i wklej adres callbacku
Dwie równoległe sesje psują Playwrighta	Obie używają jednego trwałego profilu przeglądarki	Dodaj --isolated do argumentów Playwrighta

Debugowanie na poziomie transportu, wspólne dla wszystkich klientów, opisuje strona problemy z połączeniem MCP, a co robić, gdy zadanie posypie się w połowie, wyjaśnia odzyskiwanie po błędach w Codexie.

Dokąd dalej z MCP w Codexie

Odzyskiwanie po błędach w Codexie Następny krok szybkiego startu: cofanie złych edycji, błędy sandboxa i zawieszone zadania.

Połącz Codexa z GitHubem Recenzje PR-ów i wzmianki @codex, które dobrze łączą się z serwerem GitHub MCP.

Katalog serwerów MCP Zweryfikowane polecenia instalacji najważniejszych serwerów dla każdego narzędzia.

Zabezpieczanie serwerów MCP Zakresy tokenów, prompt injection przez wyniki narzędzi i ocena serwerów.