Wewnętrzne serwery MCP — zbuduj tylko brakujący interfejs

Wewnętrzny serwer MCP to usługa Model Context Protocol, którą organizacja buduje, by agenci kodujący sięgali do wewnętrznego systemu, którego żadna utrzymywana integracja nie udostępnia bezpiecznie. Maksimum w pytaniu Q7 CTO Scorecard daje tylko, gdy zamyka zmierzoną, powtarzalną lukę dostępu wąskimi narzędziami (najpierw tylko do odczytu), ma właściciela, autoryzację least privilege, testy kontraktowe, monitoring i kryteria wycofania.

Ta strona jest dla CTO, który decyduje, co buduje zespół platformowy, i dla tech leada, który będzie właścicielem wyniku. Sytuacja: inżynierowie codziennie wklejają do sesji agenta ten sam arkusz własności serwisów, stan feature flag i linki do runbooków, a ktoś proponuje „serwer MCP do wszystkiego, co wewnętrzne”. Pół roku później są cztery serwery, jeden ma ogólne narzędzie SQL, dwa nie mają właściciela i nikt nie potrafi powiedzieć, czy którykolwiek przyspieszył jakiekolwiek zadanie.

Co daje uzasadniony wewnętrzny serwis MCP

Czteropoziomową tabelę punktacji Q7, dzięki której umiejscowisz organizację i nazwiesz dowody podnoszące wynik.
Tabelę decyzyjną, która dobiera najmniejszy interfejs do luki: istniejący serwer, CLI ze skillem, generowany plik albo własny serwer.
Szablony opisu luki i kontraktu narzędzia do przyjęcia bez zmian.
Zweryfikowane komendy podłączające jeden wewnętrzny serwer w Claude Code, Codeksie i Cursorze.
Automatyczne bramki, które dowodzą, że serwer działa w każdym kliencie i każdej erze protokołu, bez czytania każdego wywołania narzędzia.
Metryki i regułę wycofania, które utrzymują liczbę serwerów w ryzach, oraz typowe awarie z krokami naprawy.

Jak CTO Scorecard Q7 punktuje wewnętrzne serwery MCP?

Scorecard pyta: „Czy wewnętrzne serwisy MCP bezpiecznie rozwiązują zmierzone, powtarzalne luki dostępu?”. Liczba serwerów nigdy nie daje punktów. Dają je dowody.

Punkty	Odpowiedź	Dowód, który ją uzasadnia
0	Nie	Brak albo serwery, których nikt nie umie wymienić.
1	Istnieje prototyp (proof of concept), ale luka, właściciel lub kontrole nie są ustalone	Repozytorium i demo. Brak baseline’u, brak właściciela w katalogu serwisów, współdzielony token.
2	Uzasadniony wąski serwis działa z podstawową odpowiedzialnością właściciela i monitoringiem	Opis luki z baseline’em, wskazany z nazwy właściciel, dashboard z wywołaniami i błędami.
3	Uzasadnione wewnętrzne serwisy MCP z właścicielami, minimalnymi uprawnieniami, dokumentacją, zestawami danych testowych (fixtures), monitoringiem i kryteriami wycofania	Wszystko z poziomu 2 oraz kontrakt dla każdego narzędzia, autoryzacja per użytkownik, przebieg testów kontraktowych w CI, zestaw danych testowych, kwartalny przegląd i spisana reguła wycofania.

Poziom 3 da się osiągnąć z jednym serwerem. Organizacja z jednym dobrze prowadzonym serwerem dostaje więcej punktów niż ta z sześcioma serwerami bez właściciela.

Kiedy wewnętrzny serwer MCP jest właściwym interfejsem?

Większość luk dostępu ma tańsze rozwiązanie niż nowa usługa. Serwer MCP dokłada uwierzytelniany endpoint, schemat ładowany przez każdego klienta do kontekstu, aktualizacje protokołu i dyżury. Przejdź tabelę od góry i zatrzymaj się na pierwszym pasującym wierszu.

Luka wygląda tak…	Najmniejszy interfejs	Dlaczego wygrywa
System publiczny lub dostawcy zewnętrznego, który ma już utrzymywany serwer MCP (GitHub, Sentry, baza danych)	Istniejący serwer w trybie tylko do odczytu	Utrzymuje go ktoś inny. Zobacz podstawowe serwery MCP.
Wewnętrzny system z dobrym CLI lub REST API, używany przez jeden zespół	CLI plus współdzielony skill opisujący, jak je wywołać	Żadnej nowej usługi. Agent i tak uruchamia komendy.
Wolno zmieniające się dane referencyjne (własność, decyzje architektoniczne, katalog API)	Plik generowany w repozytorium, odświeżany przez CI	Zero powierzchni w runtime, zmiany widać w diffach.
Dane na żywo, potrzebne kilku zespołom, w więcej niż jednym kliencie agenta, z uprawnieniami per użytkownik	Wewnętrzny serwer MCP	Jeden kontrolowany interfejs, który rozumieją Claude Code, Codex i Cursor.

Buduj serwer, gdy spełnione są wszystkie cztery warunki z ostatniego wiersza: dane są na żywo, potrzeba obejmuje kilka zespołów, korzysta z niej więcej niż jeden klient, a dostęp zależy od tego, kto pyta. Jeśli spełniony jest tylko jeden, zwykle wystarczy skill albo generowany plik.

Zbuduj wewnętrzny serwer MCP w siedmiu krokach

Kolejność ma znaczenie. Każdy krok daje dowód, na którym opiera się następny, a pominięcie dwóch pierwszych to najczęstsza droga do wyniku 1.

Napisz opis luki i zmierz baseline. Przez dwa tygodnie zapisuj zadanie, kto je wykonuje, jak często, ile trwa i jak dziś zawodzi. Użyj szablonu opisu luki poniżej. Bez baseline’u nie udowodnisz, że serwer pomógł, a Q7 pyta o luki „zmierzone”.
Najpierw sprawdź prostsze opcje. Przejdź tabelę decyzyjną z opisem luki w ręku. Zapisz, którą opcję odrzuciłeś i dlaczego, bo zapyta o to kwartalny przegląd.
Napisz jeden kontrakt na każde narzędzie. Projektuj operacje na poziomie zadania, a nie surowy dostęp. find_service_owner(endpoint) zwracające zespół, repozytorium i datę ostatniej weryfikacji to ograniczona operacja biznesowa. query_internal_database(sql) daje każdemu podłączonemu agentowi otwartą powierzchnię uprawnień. Zacznij od narzędzi tylko do odczytu i ogranicz rozmiar każdego wyniku.
Zaimplementuj najmniejszy serwer, który spełnia kontrakty. Opakuj istniejące wewnętrzne API, a nie bazę danych za nim, żeby nadal działała autoryzacja API. Budowa własnego serwera MCP opisuje kod SDK, transporty i pakowanie. Udostępnij serwer przez Streamable HTTP, żeby mieć jedno wdrożenie, a nie proces na każdym laptopie.
Dodaj kontrole produkcyjne. OAuth per użytkownik zamiast współdzielonego tokenu serwisowego, autoryzacja per narzędzie, logi audytu z nazwą użytkownika i narzędzia, limity zapytań, timeouty i żadnego narzędzia zapisującego, dopóki narzędzia do odczytu nie udowodnią swojej wartości. Model bezpieczeństwa MCP (Q8) definiuje allowlistę, reguły akceptacji zapisów i adwersarialne dane testowe, które obowiązują ten serwer jak każdy inny.
Podłącz serwer w każdym wspieranym kliencie i dodaj go do allowlisty. Użyj komend z następnej sekcji, a potem dopisz dokładny URL serwera do zarządzanej allowlisty. Zarządzana polityka opisuje, jak dystrybuować tę konfigurację.
Awansuj na podstawie dowodów. Serwer wychodzi z pilotażu dopiero wtedy, gdy bramki kontraktowe przechodzą w CI, a metryki są lepsze od baseline’u z kroku 1. W przeciwnym razie zawęź go albo wycofaj.

Szablony opisu luki i kontraktu narzędzia

Trzymaj oba pliki w repozytorium serwera, obok kodu. Opis luki to „zmierzone” z pytania Q7; kontrakt to coś, co recenzenci zatwierdzają zamiast czytać implementację.

gap: Agents cannot find the owning team and runbook for an internal endpoint
users: [payments, checkout, platform]        # teams that hit the gap
frequency_per_week: 40                       # counted from 2 weeks of logged sessions
current_path: Search the ownership sheet, then ask in #platform-help
current_lead_time_minutes_p50: 12            # measured, not estimated
failure_modes: [stale sheet, wrong team paged, runbook link missing]
alternatives_rejected:
  existing_server: none exposes our service catalog
  cli_plus_skill: catalog API needs per-user auth the CLI lacks
  generated_file: ownership changes daily; a file is stale within hours
success_metric: p50 lead time under 2 minutes, wrong-owner rate under 2%
owner: platform-team (on-call rota "catalog")
review_date: 2026-12-15
retire_if: fewer than 10 distinct users in a quarter, or success metric missed twice

name: find_service_owner
purpose: Return the owning team, repository, and runbook for one internal endpoint
non_purpose: Listing all services, editing ownership, paging anyone
input:  { endpoint: "string, path such as /v1/invoices, max 200 chars" }
output: { team: string, repository: string, runbook_url: string, last_verified: "ISO 8601" }
data_classification: internal
authorization: caller's own OAuth identity; catalog API enforces team visibility
side_effects: none                           # read-only; annotated readOnlyHint
limits: { timeout_ms: 5000, max_results: 1, rate_per_user_per_minute: 30 }
errors: [NOT_FOUND, FORBIDDEN, UPSTREAM_TIMEOUT]   # agent reports these, never guesses
version: 1.2.0
owner: platform-team
deprecation: announce two releases ahead; old version served for 30 days

Liczby w opisie luki to miejsca na twoje własne pomiary. Linia retire_if to kryterium wycofania, o które pyta Q7. Zapisujesz je przed startem, żeby później nikt nie musiał o nie walczyć.

Jak podłączyć wewnętrzny serwer MCP w Claude Code, Codeksie i Cursorze?

Serwer jest ten sam, rejestracja różni się między klientami. Komendy sprawdzone w Claude Code 2.1.283 i Codeksie 0.157.1 dnia 2026-09-26. Każdy użytkownik uwierzytelnia się jako on sam, więc token nie trafia do żadnego pliku.

Uruchom w terminalu w katalogu głównym repozytorium. Zakres projektu zapisuje .mcp.json, który commitujesz, żeby każdy inżynier dostał ten sam wpis:

claude mcp add --transport http --scope project catalog https://catalog.mcp.internal.example.com/mcp
claude mcp login catalog

Zapisany wpis to {"mcpServers": {"catalog": {"type": "http", "url": "https://catalog.mcp.internal.example.com/mcp"}}}. Narzędzia pojawiają się jako mcp__catalog__find_service_owner i tej nazwy używasz w regułach uprawnień oraz w --allowedTools. Każdy inżynier raz zatwierdza serwer projektu przy pierwszym użyciu; do tego czasu claude mcp list pokazuje go jako oczekujący na zatwierdzenie (Claude Code 2.1.283).

Uruchom w terminalu. codex mcp add zapisuje wpis w ~/.codex/config.toml użytkownika:

codex mcp add catalog --url https://catalog.mcp.internal.example.com/mcp
codex mcp login catalog

Ogranicz listę narzędzi w tym samym wpisie, żeby nowe narzędzie na serwerze nie trafiło do agentów, dopóki go tu nie dopiszesz:

[mcp_servers.catalog]
url = "https://catalog.mcp.internal.example.com/mcp"
enabled_tools = ["find_service_owner", "get_runbook"]

Dodaj serwer do .cursor/mcp.json w repozytorium i zacommituj plik:

{
  "mcpServers": {
    "catalog": { "url": "https://catalog.mcp.internal.example.com/mcp" }
  }
}

Dokumentacja MCP Cursora wymienia OAuth dla zdalnych serwerów; przed wdrożeniem potwierdź przebieg logowania na jednej maszynie.

Jak udowodnić, że wewnętrzny serwer działa, bez czytania każdego wywołania?

Nikt nie przegląda pojedynczych wywołań narzędzi. Dowód niosą cztery automatyczne bramki i jedno kwartalne zatwierdzenie.

1. Bramki kontraktowe w CI, przy każdej zmianie serwera. MCP Inspector CLI (@modelcontextprotocol/inspector 2.8.0 na 2026-09-26) listuje narzędzia w każdej erze protokołu i sprawdza przenośność schematów. Uruchom go na wdrożeniu stagingowym:

URL=https://catalog.staging.mcp.internal.example.com/mcp
npx @modelcontextprotocol/inspector@2.8.0 --cli "$URL" --protocol-era legacy --method tools/list --strict
npx @modelcontextprotocol/inspector@2.8.0 --cli "$URL" --protocol-era modern --method tools/list --strict
npx @modelcontextprotocol/inspector@2.8.0 --cli "$URL" --method tools/call \
  --tool-name find_service_owner --tool-arg endpoint=/v1/invoices

Serwer, który nie oferuje 2026-07-28, oblewa wywołanie modern z niezerowym kodem wyjścia, a --strict kończy się kodem 6 przy problemie z przenośnością schematu o wadze error. Oba zatrzymują pipeline. Token dla stagingu podaj przez opcje OAuth Inspectora (--stored-auth-only w przebiegach nieinteraktywnych), nigdy jako dosłowny nagłówek.

2. Zestaw danych testowych. Zamień listę błędów z każdego kontraktu na testy: nieznany endpoint zwraca NOT_FOUND, użytkownik spoza zespołu dostaje FORBIDDEN, wolny upstream zwraca UPSTREAM_TIMEOUT w ramach limitu, a zbyt duże wejście jest odrzucane. Przypadki adwersarialne (wstrzyknięte instrukcje w zwracanych danych, powtórzone zapisy, korelacja logów audytu) pochodzą z zestawu danych testowych Q8.

3. Eval na złotych zadaniach. Trzymaj 10–20 prawdziwych pytań z opisu luki ze znanymi odpowiedziami i uruchamiaj je w trybie nieinteraktywnym (headless), z załadowanym tylko wewnętrznym serwerem. eval/catalog.mcp.json zawiera ten sam wpis catalog co .mcp.json, a --strict-mcp-config pomija wszystkie inne skonfigurowane serwery:

claude -p "Who owns /v1/invoices and where is its runbook? Answer as JSON with team and runbook_url." \
  --strict-mcp-config --mcp-config eval/catalog.mcp.json \
  --allowedTools "mcp__catalog__find_service_owner" --output-format json

Porównaj każdą odpowiedź z oczekiwaną w skrypcie. W Codeksie odizoluj przebieg w ten sam sposób: --ignore-user-config pomija $CODEX_HOME/config.toml (i wszystkie skonfigurowane tam serwery), a nadpisania -c definiują catalog jako jedyny serwer MCP w tym przebiegu. Uruchamiaj go z katalogu bez projektowego .codex/config.toml, bo inaczej serwery z tego pliku dołączą do przebiegu (Codex 0.157.1):

codex exec --sandbox read-only --ignore-user-config \
  -c 'mcp_servers.catalog.url="https://catalog.mcp.internal.example.com/mcp"' \
  -c 'mcp_servers.catalog.enabled_tools=["find_service_owner"]' \
  "Who owns /v1/invoices and where is its runbook? Answer as JSON with team and runbook_url."

Ta strona nie opisuje dla Cursora ścieżki evalu w trybie nieinteraktywnym, więc zastępują go evale w Claude Code i Codeksie: sprawdzają ten sam serwer i te same kontrakty narzędzi. Spadek odsetka poprawnych odpowiedzi po wydaniu serwera blokuje to wydanie.

4. Sygnały z produkcji. Dashboard właściciela pokazuje wywołania na tydzień, liczbę różnych użytkowników, odsetek błędów, odmowy, latencję p95 i kompletność logów audytu, a alert włącza się, gdy którakolwiek wartość wyjdzie poza zakres.

Kwartalne zatwierdzenie. Właściciel porównuje metryki z success_metric z opisu luki, stosuje retire_if i zapisuje decyzję: zostawić, zawęzić albo wycofać. CTO lub lider platformy kontrasygnuje. Ten zapis jest dowodem na poziom 3 w Q7.

Prompty do przeglądu projektu wewnętrznego MCP

Działają tak samo w Claude Code, Codeksie i Cursorze. Uruchamiaj je z otwartym repozytorium serwera.

Read mcp/catalog/gap-brief.yaml. Decide whether an internal MCP server is justified. Evaluate, in this order: an existing maintained MCP server, the internal CLI or REST API plus a skill, a file generated by CI, and a custom MCP server. For each option state whether it meets the success_metric, what it costs to operate, and what it cannot do. Recommend the smallest option that meets the metric, and list the evidence we would need at the first quarterly review to keep it. Do not write any code.

Review every file in mcp/catalog/tools/. Flag any tool that accepts raw SQL, shell commands, file paths, arbitrary URLs, or free-form queries; any tool without a result limit, timeout, or error list; any write tool without a named approval; and any tool that authenticates with a shared service identity instead of the caller's. For each finding, propose a narrower task-level replacement with its input and output schema. Output a table: tool, finding, severity, replacement.

For each contract in mcp/catalog/tools/, write automated tests against the staging server that cover: one valid call with a known answer, malformed input, an input over the size limit, a caller without permission (expect FORBIDDEN), an unknown key (expect NOT_FOUND), an upstream timeout (expect UPSTREAM_TIMEOUT within timeout_ms), and returned data that contains the text "ignore previous instructions". Every test must fail if the server's behaviour changes. Do not call any write tool, and read credentials only from the environment.

Co psuje się w wewnętrznych serwerach MCP i jak to naprawić?

Platforma bez potrzeby. Serwery powstały, żeby odhaczyć checklistę dojrzałości, i nikt ich nie używa, a nadal wymagają auth, aktualizacji protokołu i dyżurów. Naprawa: napisz wstecznie opis luki dla każdego serwera; wycofaj każdy, który nie pokaże baseline’u i obecnych użytkowników.

Narzędzie ogólne. Narzędzie run_query albo call_api sprawiło, że serwer nadaje się do wszystkiego i do niczego nie jest bezpieczny. Naprawa: odczytaj z logu audytu dziesięć najczęstszych wywołań, zamień każde w narzędzie na poziomie zadania, a potem usuń narzędzie ogólne i ogłoś datę.

Działa w Claude Code, nie działa w Codeksie. Serwer implementuje tylko erę 2026-07-28 albo tylko starszą, gdy klient się zaktualizuje. Naprawa: dodaj do CI obie kontrole --protocol-era i obsługuj obie ery, dopóki wszyscy wspierani klienci nie negocjują nowej.

Współdzielony token serwisowy. Każdy użytkownik dostaje uprawnienia tokenu, a log audytu pokazuje jedną tożsamość. Naprawa: przejdź na OAuth per użytkownik, potwierdź, że log wskazuje pojedynczych użytkowników, a potem unieważnij token. Opcje opisuje strona Tożsamość agentów, poświadczenia i sekrety.

Rozrost narzędzi zjada kontekst. Schemat każdego narzędzia trafia do kontekstu agenta, a serwer z 40 narzędziami wypiera samo zadanie. Naprawa: trzymaj krótką listę narzędzi, ograniczaj ją per klient przez enabled_tools lub reguły uprawnień i zajrzyj do ograniczania kosztu tokenów MCP.

Zmiana schematu po cichu psuje klientów. Pole o zmienionej nazwie zwraca undefined, a agent zgaduje odpowiedź. Naprawa: wersjonuj każdy kontrakt, trzymaj eval na złotych zadaniach w pipeline wydania i obsługuj starą wersję przez okno deprecjacji zapisane w kontrakcie.

Właściciel odszedł. Reorganizacja zlikwidowała zespół, a serwer działa dalej bez nikogo na dyżurze. Naprawa: uczyń pole właściciela obowiązkowym wpisem w katalogu serwisów, ustaw alert, gdy wskazuje rozwiązany zespół, i zastosuj retire_if na najbliższym przeglądzie.

Dokąd dalej z wewnętrznymi serwerami MCP

Model bezpieczeństwa MCP (Q8): allowlista, akceptacja per narzędzie i adwersarialne dane testowe, które ten serwer musi przejść.
Budowa własnego serwera MCP: kod SDK, transporty i pakowanie stojące za krokiem 4.
MCP 2026-07-28: migracja serwera i testy obu er protokołu.
Rejestry i bramki MCP: publikacja zatwierdzonego katalogu i audyt wywołań przez bramkę.
Współdzielone skille (lżejsza alternatywa): kiedy CLI ze skillem zamyka lukę bez nowej usługi.
Zespół platformowy: kto jest właścicielem wewnętrznych narzędzi dla agentów i jak są finansowane.
Dzielenie się wiedzą (Q20): kontrakty, dane testowe i incydenty w miejscu, gdzie da się je znaleźć.
Klucz odpowiedzi CTO: każde pytanie scorecardu i jego kanoniczna strona.