Konfiguracja serwerów MCP w Cursorze

Cursor łączy swojego agenta z serwerami MCP (Model Context Protocol) wymienionymi w pliku JSON: .cursor/mcp.json dla jednego projektu albo ~/.cursor/mcp.json dla wszystkich projektów. Każdy wpis to lokalne polecenie, które Cursor uruchamia, albo zdalny adres URL. Serwer jest gotowy dopiero wtedy, gdy odpowiedzi agenta opierają się na prawdziwym wywołaniu narzędzia z minimalnymi uprawnieniami.

Ta strona jest dla programisty, który podłącza Cursora do systemów używanych na co dzień, i dla tech leada, który chce jednego wspólnego pliku MCP dla całego zespołu, przeglądanego w pull requestach. Pytasz agenta, czy tabela users ma kolumnę email_verified. Agent znajduje migrację sprzed pół roku i odpowiada z pełnym przekonaniem, tyle że błędnie, bo późniejszy hotfix usunął tę kolumnę. Z podłączonym serwerem bazy danych agent czyta aktualny schemat. Dodanie serwera zajmuje pięć minut. Reszta tej strony dotyczy tego, jak zapewnić, że serwer może tylko czytać, i jak poznać, że agent naprawdę z niego skorzystał.

Co daje konfiguracja MCP w Cursorze

• Plik .cursor/mcp.json zapisany w repozytorium, z serwerami GitHub, Postgres i Playwright, bez żadnego sekretu w środku.
• Poświadczenia tylko do odczytu dla każdego serwera, który nie musi niczego zapisywać.
• Prompt testowy, który sprawdza, czy każdy serwer odpowiada, i prompt dowodowy, który pokazuje, które odpowiedzi pochodzą z narzędzia.
• Tabelę „objaw → naprawa” dla serwerów, które się nie uruchamiają, nie uwierzytelniają albo nigdy nie są wywoływane.

Gdzie Cursor czyta konfigurację MCP?

Cursor łączy dwa pliki. Oba mają ten sam kształt: obiekt mcpServers na najwyższym poziomie i jeden wpis na serwer.

Zakres	Plik	Do czego
Projekt	.cursor/mcp.json w katalogu głównym repozytorium	Serwery potrzebne całemu zespołowi w tym kodzie. Dodaj go do repozytorium.
Globalny	~/.cursor/mcp.json	Prywatne serwery, których chcesz w każdym projekcie.

Wpis to serwer lokalny (stdio) albo zdalny; każdy z nich może mieć blok auth. Poniższe klucze pochodzą ze schematu mcp.json w oficjalnym pakiecie Cursora @cursor/sdk (wersja 1.0.32, sprawdzone 2026-09-26), bo cursor.com był tego dnia niedostępny z naszego środowiska weryfikacji. Tego schematu nie sprawdzaliśmy ponownie na cursor.com 2026-10-12; @cursor/sdk ma 2026-10-07 wersję 1.0.37.

Rodzaj	Klucze	Przykład
Lokalny serwer (stdio), który uruchamia Cursor	command, args, env, cwd, envFile	npx @playwright/mcp@latest
Zdalny serwer po HTTP	url, headers	https://api.githubcopilot.com/mcp/readonly
Opcjonalnie w obu rodzajach, gdy serwer wymaga wcześniej zarejestrowanego klienta OAuth	auth z CLIENT_ID, opcjonalnym CLIENT_SECRET i opcjonalnym scopes	wewnętrzny serwer firmy

Sekrety zapisuj jako odwołania ${env:NAZWA}. Cursor przy wczytywaniu pliku podstawia wartość zmiennej środowiskowej NAZWA, więc sam plik nie zawiera tokenu i można go dodać do repozytorium.

Podłącz pierwszy serwer: GitHub tylko do odczytu

Serwer hostowany przez GitHuba nie wymaga lokalnego środowiska uruchomieniowego i ma punkt końcowy tylko do odczytu. Dzięki temu jest najbezpieczniejszym pierwszym serwerem: agent może czytać issues, pull requesty i logi CI, ale nie może pushować, mergować ani komentować.

1. Utwórz fine-grained personal access token. W GitHubie przejdź do Settings → Developer settings → Personal access tokens → Fine-grained tokens. Ogranicz go do repozytoriów, nad którymi pracujesz, i nadaj dostęp tylko do odczytu do zawartości, issues, pull requestów i Actions.

2. Umieść token w środowisku, a nie w pliku w repozytorium. Najpierw zapisz go w pliku poza repozytorium, który możesz czytać tylko ty:

   mkdir -p ~/.config/tokens
   (umask 077; cat > ~/.config/tokens/github-mcp)   # wklej token, naciśnij Enter, potem Ctrl-D

   Następnie dodaj tę linię do profilu powłoki (~/.zshrc lub ~/.bashrc) i otwórz nowy terminal:

   export GITHUB_PAT="$(cat ~/.config/tokens/github-mcp)"

3. Utwórz .cursor/mcp.json w katalogu głównym repozytorium:

   {
     "mcpServers": {
       "github": {
         "url": "https://api.githubcopilot.com/mcp/readonly",
         "headers": {
           "Authorization": "Bearer ${env:GITHUB_PAT}"
         }
       }
     }
   }

   Przyrostek /readonly to oficjalny punkt końcowy GitHuba tylko do odczytu. GitHub oferuje ten sam przyrostek dla każdego zestawu narzędzi, na przykład https://api.githubcopilot.com/mcp/x/actions/readonly. Usuń go tylko wtedy, gdy agent ma otwierać pull requesty albo komentować.

4. Zamknij Cursora całkowicie i uruchom go ponownie. Cursor czyta środowisko i mcp.json przy starcie. Nowe okno czatu nie wystarczy.

5. Sprawdź status serwera. Otwórz ustawienia Cursora i znajdź sekcję MCP (przewodnik instalacji GitHuba nazywa ją Tools & Integrations → MCP Tools, inne przewodniki po prostu MCP). Zielona kropka przy github oznacza, że Cursor połączył się z serwerem i wczytał jego narzędzia. Czerwona kropka albo błąd oznacza, że serwer się nie uruchomił. Poprawki znajdziesz w tabeli w sekcji Gdy konfiguracja MCP w Cursorze zawodzi.

6. Uruchom poniższy test w nowym czacie Agent. Powinny pojawić się wywołania narzędzi, a nie sama proza.

Prompt do skopiowania: test wszystkich serwerów MCP

List every MCP server and tool you can call right now, grouped by server.
Then make exactly one read-only call per server:
- github: list the 3 most recently updated open pull requests in this repository
- postgres: list the columns of the users table
- playwright: open http://localhost:3000 and return the page title
For each call, print the server name, the tool name, the arguments you passed and
the first 10 lines of the raw result. If a server or tool is missing, say so and
do not guess the answer.

Jeśli serwer jest na liście, ale wywołanie się nie udaje, serwer wystartował, a poświadczenia są złe. Jeśli serwera nie ma na liście, w ogóle się nie uruchomił.

Dodaj bazę danych i przeglądarkę

Większości zespołów kolejny największy zysk dają dwa serwery: baza danych, którą agent może obejrzeć, i przeglądarka, którą może sterować.

Postgres z rolą tylko do odczytu

Postgres MCP Pro (crystaldba/postgres-mcp) to pakiet Pythona z PyPI, więc uruchamiasz go przez uvx, a nie npx. Flaga --access-mode=restricted wykonuje zapytania w transakcjach tylko do odczytu z limitem czasu wykonania. Ostatnie wydanie na PyPI to 0.3.0 (maj 2025); jeśli potrzebujesz aktywnie rozwijanej opcji, zobacz DBHub w przewodniku po serwerach MCP dla baz danych.

{
  "mcpServers": {
    "postgres": {
      "command": "uvx",
      "args": ["postgres-mcp", "--access-mode=restricted"],
      "env": {
        "DATABASE_URI": "${env:DATABASE_URI}"
      }
    }
  }
}

Serwer czyta DATABASE_URI, a nie DATABASE_URL. Gdy ustawione jest tylko DATABASE_URL, serwer kończy działanie przy starcie z błędem „No database URL provided” i ma czerwoną kropkę. Dla serwerów stdio możesz też ustawić "envFile": ".env.mcp" i trzymać zmienne w pliku ignorowanym przez git. Dzięki temu nie ma znaczenia, że Cursor może nie widzieć zmiennych z profilu powłoki.

Tryb restricted nie jest granicą uprawnień

Traktuj --access-mode=restricted jako drugą warstwę. Pierwszą jest rola bazy danych w DATABASE_URI: utwórz rolę z samymi uprawnieniami SELECT i kieruj ją na lokalną bazę albo replikę do odczytu, nigdy na główną bazę produkcyjną. Pakiet npm @modelcontextprotocol/server-postgres jest oznaczony jako deprecated, a jego repozytorium zarchiwizowane, więc go nie używaj. Więcej opcji, w tym DBHub dla MySQL i SQL Servera, znajdziesz w przewodniku po serwerach MCP dla baz danych.

Playwright do sprawdzania interfejsu, który agent właśnie zmienił

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest", "--isolated"]
    }
  }
}

--isolated trzyma profil przeglądarki w pamięci. README Playwrighta ostrzega, że trwałego profilu może naraz używać tylko jedna przeglądarka, więc dwóch agentów albo dwa okna Cursora na domyślnym profilu wchodzą sobie w drogę. To samo README sugeruje, że agentom kodującym może lepiej służyć CLI Playwrighta ze skillami niż MCP, bo schematy narzędzi MCP i zrzuty stron zajmują kontekst. Zacznij od MCP. Przełącz się, gdy czaty zaczną dobijać do limitu kontekstu. Obie drogi opisuje przewodnik po Playwright MCP.

Wspólny plik zespołu

Połącz trzy wpisy w jeden .cursor/mcp.json i dodaj go do repozytorium:

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/readonly",
      "headers": { "Authorization": "Bearer ${env:GITHUB_PAT}" }
    },
    "postgres": {
      "command": "uvx",
      "args": ["postgres-mcp", "--access-mode=restricted"],
      "env": { "DATABASE_URI": "${env:DATABASE_URI}" }
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest", "--isolated"]
    }
  }
}

Każda osoba w zespole potrzebuje wtedy tylko dwóch zmiennych środowiskowych, uv dla uvx i Node.js dla npx. Dopisz te trzy wymagania do README obok pliku.

Zdalne serwery z logowaniem OAuth

Wiele hostowanych serwerów, na przykład Linear (https://mcp.linear.app/mcp), potrzebuje tylko adresu URL. Cursor przeprowadza logowanie OAuth w przeglądarce przy pierwszym połączeniu, więc nie ma tokenu do przechowania:

{
  "mcpServers": {
    "linear": { "url": "https://mcp.linear.app/mcp" }
  }
}

Blok auth dodawaj tylko wtedy, gdy dokumentacja serwera daje ci wcześniej zarejestrowany identyfikator klienta. Sekret klienta zapisz przez ${env:…}, jak każdy inny sekret.

Skąd wiesz, że agent użył narzędzia, a nie zgadywał?

Podłączony serwer nie gwarantuje, że agent go wywołał. Agent decyduje przy każdym prompcie, a pewna siebie odpowiedź zbudowana na starym pliku migracji wygląda tak samo jak odpowiedź z aktualnego schematu. Sprawdzaj dowody, nie prozę:

1. Szukaj wywołań narzędzi w historii czatu. Cursor pokazuje w czacie każde wywołanie narzędzia MCP i możesz je rozwinąć, żeby zobaczyć, co zostało wysłane i co wróciło. Odpowiedź o bazie danych bez wywołania narzędzia postgres nad nią pochodzi z twojego kodu, nie z bazy.
2. Proś o surowy wynik. Prompt dowodowy poniżej każe agentowi zacytować, co zwróciło narzędzie, więc rozbieżność między cytatem a wnioskiem widać od razu.
3. Sprawdź jeden fakt deterministycznym poleceniem. Przy pytaniach o schemat psql "$DATABASE_URI" -c '\d users' w terminalu rozstrzyga sprawę w jednej linii. Rób to przez pierwsze kilka razy, gdy polegasz na serwerze, a nie przy każdym prompcie.
4. Resztę niech sprawdzą testy. Gdy dane z MCP trafiają do zmiany w kodzie, na przykład do migracji, bramka jest taka sama jak dla każdej zmiany agenta: migracja wchodzi na świeżą lokalną bazę, a zestaw testów przechodzi. Przeglądasz wyniki testów i intencję migracji, a nie każdą wygenerowaną linię.
5. Niech poświadczenia zawodzą głośno. Z tokenami i rolami tylko do odczytu przypadkowy zapis kończy się błędem zamiast zmiany danych. Błąd w czacie to dowód, że zabezpieczenie działa.

Prompt do skopiowania: migracja oparta na schemacie, z dowodami

Use the postgres MCP server to read the current definition of the users table,
including columns, types, defaults and indexes. Quote the raw tool output.
Then write a migration in our existing migration style that adds
email_verified boolean NOT NULL DEFAULT false and an index on it.
Before you finish, list every assumption you made that did not come from a
tool result, and run the migration test command from our README.

Prompt do skopiowania: od czerwonego CI do planu poprawki

Use the github MCP server to find the most recent failed GitHub Actions run on
the current branch. Fetch the failing job's log and quote the first error with
its step name. Find the code that causes it, propose the smallest fix, and tell
me which test proves the fix. Do not edit files until I approve the plan.

Tech lead zatwierdza, jakie serwery zawiera plik zespołu i co może każde poświadczenie. Każdy programista zatwierdza własną zmianę na podstawie testów, jak przy każdej innej pracy agenta. Nikt nie musi czytać ruchu MCP linia po linii.

Jak bezpiecznie używać serwerów MCP w zespole

• Trzymaj plik w repozytorium, token nigdy. Plik .cursor/mcp.json z samymi odwołaniami ${env:…} da się przejrzeć w pull requeście. Token wklejony do pliku to token, który już wyciekł — nawet w prywatnym repozytorium.
• Przeczytaj .cursor/mcp.json sklonowanego repozytorium, zanim zatwierdzisz jego serwery. Wpis stdio to polecenie, które uruchamia się na twojej maszynie z twoimi zmiennymi środowiskowymi. Traktuj go jak skrypt z tego samego źródła.
• Nie wyłączaj zatwierdzania dla serwerów, które zapisują. Sposób, w jaki Cursor zatwierdza wywołania narzędzi, również MCP, ustawiają tryby uruchamiania agenta (Auto-review, Allowlist albo Run Everything; dokumentacja Agent security Cursora). Bez zatwierdzania pozwalaj działać tylko serwerom tylko do odczytu i sprawdzaj to ustawienie przy każdym nowym serwerze, który może zapisywać.
• Wybieraj oficjalny serwer dostawcy. GitHub, Playwright, Linear i Sentry utrzymują własne serwery. Społecznościowe nakładki na to samo API dokładają opiekuna, którego nikt w zespole nie sprawdził.
• Wczytuj tylko to, czego używasz. Każdy podłączony serwer dodaje definicje swoich narzędzi do kontekstu agenta, zanim cokolwiek napiszesz. Wyłączaj na liście MCP w ustawieniach serwery i narzędzia niepotrzebne w bieżącym projekcie. Większe oszczędności opisuje przewodnik o obniżaniu kosztu tokenów MCP.

Skanowanie konfiguracji, ograniczanie prompt injection i zespołową politykę zatwierdzania serwerów opisuje przewodnik o zabezpieczaniu serwerów MCP.

Gdy konfiguracja MCP w Cursorze zawodzi

Objaw	Prawdopodobna przyczyna	Naprawa
Czerwona kropka albo brak wpisu dla serwera stdio	Polecenia (npx, uvx, docker) nie ma w PATH, który widzi Cursor, albo JSON jest niepoprawny	Uruchom dokładnie te command i args w terminalu. Zainstaluj brakujące środowisko. Sprawdź plik poleceniem python3 -m json.tool .cursor/mcp.json. Uruchom Cursora ponownie.
401 albo „Bad credentials” z GitHuba	${env:GITHUB_PAT} było puste przy starcie Cursora albo token nie ma dostępu do repozytorium	Sprawdź, czy echo $GITHUB_PAT wypisuje wartość w nowym terminalu. Cursor uruchomiony z Docka albo menu Start może nie dziedziczyć profilu powłoki. Zamknij go i uruchom ze środowiska, które ma tę zmienną, albo użyj envFile dla serwerów stdio.
Czerwona kropka przy postgres; log mówi „No database URL provided”	DATABASE_URI nie jest ustawione albo jest puste (często ustawione jest tylko DATABASE_URL)	Ustaw DATABASE_URI, całkowicie zamknij Cursora i uruchom go ponownie.
Serwer Postgres startuje, a każde zapytanie się nie udaje	Rola nie może się połączyć (zły host, hasło albo uprawnienia)	Przetestuj ten sam ciąg poleceniem psql "$DATABASE_URI" -c 'select 1'.
Narzędzia są na liście, ale agent odpowiada bez ich wywołania	Z promptu nie wynikało, że trzeba użyć narzędzia	Nazwij serwer i narzędzie w prompcie („use the postgres MCP server to…”) i poproś o surowy wynik, jak w prompcie dowodowym.
Playwright zgłasza błąd profilu albo zajętej przeglądarki	Dwie sesje dzielą jeden trwały profil przeglądarki	Dodaj --isolated albo daj każdemu oknu własny --user-data-dir.
Serwer działał wczoraj, a dziś go nie ma	@latest pobrało wydanie z breaking change albo zmienił się zdalny punkt końcowy	Przypnij wersję, na przykład @playwright/mcp@0.0.83, i podbijaj ją świadomie.
Odpowiedzi się pogarszają, gdy dodajesz serwery	Za dużo definicji narzędzi konkuruje o kontekst	Wyłącz nieużywane serwery i narzędzia w projekcie. W pliku zespołu trzymaj tylko serwery, których potrzebuje ten kod.

Błędy innych agentów i pełną listę problemów z połączeniem opisuje strona o problemach z połączeniem serwerów MCP.

Te same serwery w Claude Code i Codex

Serwery są te same, ale konfiguracji nie da się przenieść plik w plik. Claude Code czyta projektowy .mcp.json i rozwija ${VAR}. Codex zapisuje tabele [mcp_servers.<nazwa>] w ~/.codex/config.toml. Jeśli zespół używa więcej niż jednego agenta, trzymaj jedną listę serwerów i poświadczeń i na jej podstawie konfiguruj każde narzędzie. Zobacz konfigurację MCP w Claude Code i konfigurację MCP w Codex.

Co dalej z MCP w Cursorze

Ta strona następuje po workflow z PRD w szybkim starcie Cursora. Następny krok uczy, jak wybierać kontekst, który agent widzi w każdym prompcie.

Zarządzanie kontekstem Decyduj, co widzi agent, przez @-wzmianki, reguły i dokumentację, i diagnozuj problemy z kontekstem.

Startowy zestaw MCP Pięć serwerów, których potrzebuje większość zespołów, z poleceniami instalacji dla Cursora, Claude Code i Codex.

Serwer GitHub MCP Zestawy narzędzi, adresy tylko do odczytu, tryb lockdown i sytuacje, w których lepsze jest CLI gh.

Własny serwer MCP dla Cursora Udostępnij agentowi wewnętrzne API, gdy żaden istniejący serwer nie pasuje.