Wskazówki praktyczne: serwery MCP zawodzą na dwa sposoby, a oba można zapobiec. Oto one
Praktyczne wskazówki: serwery MCP zawodzą na dwa sposoby, a oba te przypadki da się zapobiec. Oto co jest potrzebne: umowy, sprawdzenia oraz miejsca na kod do wstawić dla zespołów implementujących ten wzorzec.
Poniższe notatki przedstawiają praktyczne podejście do tematu „Serwery MCP zawodzą na dwa sposoby, a oba można zapobiec. Oto warstwa ochronna”. Nacisk kładziony jest na umowy, sprawdzania oraz miejsca zastępcze dla kodu, a nie na motywacyjne aspekty. Podczas prace na etapie przeglądu najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego awarii. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Wolno preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy jakiś krok zawiedzie, awaria powinna wskazywać na konkretną odpowiedzialność, a nie na skomplikowany proces.
Serwer MCP stanowi granicę zaufania, a nie tylko element integracji
Serwer MCP funkcjonuje najlepiej na tym etapie, gdy traktowany jest jako mierzalna powierzchnia do analizy. Zapisz jeden idealny przykład działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres pracy. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy poszczególnym elementom, zdefiniuj kryteria sukcesu i odrzucaj ciche, częściowe ukończenie zadań. Używaj narzędzi o wąskich schematach oraz z wyraźnymi oznaczeniami efektów ubocznych. Hostowie muszą wiedzieć, które wywołania zmieniają stan systemu, zanim automatycznie je zatwierdzą.
Pierwsza awaria: problemy z uprawnieniami – agent ma większe zaufanie, niż wymaga zadanie
Faza błędów związanych z jedną uprawnieniem działa najlepiej, gdy traktuje się ją jako mierzalną powierzchnię do analizy. Zapisz jeden idealny zapis działania, jeden przypadek błędu oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres badania. Zapisuj czasy wykonywania operacji oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy przechodzi się z środowiska demonstracyjnego do współdzielonych środowisk. Używaj narzędzi o wąskich schematach i wyraźnych etykietach opisujących efekty uboczne. Hostowie muszą wiedzieć, które wywołania zmieniają stan systemu, zanim automatycznie je zatwierdzą.
Błąd numer dwa: błędy interfejsowe – agent nie potrafi określić, co robi dane narzędzie, ani zaufać temu, co otrzymuje w odpowiedzi
Faza „The Failure two interface failures” funkcjonuje najlepiej, gdy jest traktowana jako mierzalna powierzchnia do analizy. Zapisz jeden idealny zapis działań, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmian, zanim rozszerzysz zakres badania. Trzymaj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury. Używaj narzędzi o wąskich schematach i wyraźnych etykietach dotyczących efektów ubocznych. Hostowie muszą wiedzieć, które wywołania zmieniają stan systemu, zanim automatycznie je zatwierdzą. Faza „The Failure two interface failures” funkcjonuje najlepiej, gdy jest traktowana jako mierzalna powierzchnia do analizy. Zapisz jeden idealny zapis działań, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmian, zanim rozszerzysz zakres badania. Wolij małe, testowalne jednostki nad rozbudowane skrypty. Gdy jakiś krok się nie powiedzie, awaria powinna wskazywać na konkretną odpowiedzialność, a nie na skomplikowaną sekwencję działań.
Wzorzec, którego wszyscy nie dostrzegają: zacieśniasz wyjście modelu i ufasz danym wejściowym warstwy narzędziowej
Na etapie Wzorca, którego wszyscy nie dostrzegają, należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nazwij powstałe pliki, zdefiniuj kryteria sukcesu i odrzuć ciche, częściowe ukończenie zadania. Przy następnym kroku, który polega na pisaniu kodu lub wywoływaniu narzędzia, preferuj zstrukturyzowane wyniki z walidacją schematu zamiast tekstów w formie swobodnej.
Budowanie warstwy zabezpieczeń MCP
Aby stworzyć etap z barierką bezpieczeństwa MCP, należy najpierw określić dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić ten krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy rejestrować czasy wykonywania oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy ścieżka przechodzi z środowiska demonstracyjnego do współdzielonych środowisk. Należy uwierzytelniać się przy bramie wejściowej oraz ponownie autoryzować w warstwie danych. Sam token nie stanowi granicy między poszczególnymi usługami.
from dataclasses import dataclass
from datetime import datetime, timedelta
from typing import Optional
@dataclass
class ScopedToken:
audience: str # which MCP server this token is valid for
permissions: list[str] # e.g. ["read", "create"] - never assume "all"
issued_at: datetime
expires_at: datetime
source_user: str # who originally triggered this, for audit
def issue_scoped_token(user_token: ScopedToken, tool_name: str,
required_permissions: list[str]) -> ScopedToken:
# Never grant more than the tool declares it needs
granted = [p for p in required_permissions if p in user_token.permissions]
if set(required_permissions) - set(granted):
raise PermissionError(
f"{tool_name} requires {required_permissions}, "
f"caller only has {user_token.permissions}"
)
return ScopedToken(
audience=tool_name,
permissions=granted,
issued_at=datetime.utcnow(),
expires_at=datetime.utcnow() + timedelta(minutes=5),
source_user=user_token.source_user,
)
def enforce_audience(token: ScopedToken, expected_tool: str) -> None:
if token.audience != expected_tool:
raise PermissionError(
f"Token issued for '{token.audience}' cannot be used on '{expected_tool}'"
)
def file_support_request(customer_email: str, issue_type: str, description: str) -> dict:
ticket = create_ticket(issue_type, description)
add_comment(ticket.id, f"Filed by {customer_email}")
assign_ticket(ticket.id, team=route_by_type(issue_type))
notify_user(customer_email, ticket.id)
return {
"ticket_id": ticket.id,
"status": "open",
"assigned_team": ticket.team,
}
def safe_error(internal_message: str, request_id: str) -> dict:
# internal_message goes to your logs, never to the model
log.error(internal_message, extra={"request_id": request_id})
return {
"content": [{
"type": "text",
"text": f"Unable to complete the request. Request ID: {request_id}. "
f"Try again or contact support."
}],
"isError": True,
}
MAX_TOOLS_PER_SERVER = 15
def register_tool(server, tool):
if len(server.tools) >= MAX_TOOLS_PER_SERVER:
raise ValueError(
f"{server.name} already has {len(server.tools)} tools. "
f"Split into a domain-specific server instead of adding more."
)
server.tools.append(tool)
Jak sprawdzić, czy Twój serwer MCP już ma ten problem
Aby dowiedzieć się, jak rozpoznać etap, należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Konfigurację należy przechowywać poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury. Autoryzacja powinna odbywać się na bramce, a ponowna autoryzacja – na poziomie przetwarzania danych. Sam token nośny nie stanowi granicy między poszczególnymi użytkownikami. Aby dowiedzieć się, jak rozpoznać etap, należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy preferować małe, testowalne jednostki nad rozbudowanymi skryptami. Gdy dany krok zawiedzie, powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowaną strukturę przepływu.
Jak to pasuje do stacku produkcyjnego
Gdy przechodzisz przez etap określania, jak to pasuje, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy artefaktom, zdefiniuj sprawdzenia sukcesu i odrzuć ciche, częściowe ukończenie zadania. Zapisuj nazwę narzędzia, hash argumentów, opóźnienie oraz wynik każdej wywołania. Bez tych informacji debugowanie zajmuje godziny.
To właśnie przy wywołaniu narzędzia podejmowana jest decyzja o zaufaniu
Gdy pracujesz nad etapem wywołania narzędzia, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zapisz czas trwania oraz koszt tokena lub zapytania obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy ścieżka przechodzi z środowiska demonstracyjnego do współdzielonych środowisk. Zapisz nazwę narzędzia, hash argumentów, opóźnienie oraz wynik każdego wywołania. Bez takich informacji debugowanie agenta trwa godzinami.
Często zadawane pytania
Gdy przechodzisz przez etap Często zadawanych pytań, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Trzymaj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury. Zapisuj nazwę narzędzia, hash argumentów, opóźnienie oraz wynik każdej wywołania. Bez takich informacji debugowanie agenta trwa godzinami. Gdy przechodzisz przez etap Często zadawanych pytań, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Wolij małe, testowalne jednostki nad rozbudowane skrypty. Gdy jakiś krok się nie powiedzie, błąd powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowaną sekwencję operacji.
W fazie listy kontrolnej operacyjnej należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie wykonać dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu.
Zdokumentuj razem ścieżkę prawidłowego działania oraz ścieżkę naprawczą. Próby ponownych działań, mechanizmy ludzkiej kontroli oraz obsługa wiadomości błędnych stanowią część produktu, a nie elementy dodawane później.
Zaloguj się przy bramce i ponownie udziel uprawnień na poziomie warstwy danych. Sam token nośny nie stanowi granicy między poszczególnymi użytkownikami.
Napisz krótki podręcznik obsługi: jak rotować klucze, jak opróżnić kolejkę z zadań, jak cofnąć ostatnie operacje importu.
Niech lepsze będą małe, testowalne jednostki niż rozbudowane skrypty. Gdy jakiś krok zawiedzie, błąd powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji.
Zaloguj się przy bramce i ponownie udziel uprawnień na poziomie warstwy danych. Sam token nośny nie stanowi granicy między poszczególnymi użytkownikami.
Zanim wdrożysz cały zestaw narzędzi, zamroź wersje, utwórz dokładny zapis dla kluczowych etapów procesu oraz potwierdź kroki odwracania zmian. Środowiska współdzielone wymagają ograniczeń szybkości, weryfikacji przynależności użytkownika oraz wyraźnego właściciela odpowiedzialnego za rotację haseł. Wolimy nudną niezawodność od pomysłowych, jednorazowych demonstracji.
Uwaga dotycząca zlecenia 964498802023: nie umieszczaj kluczy dostawcy w repozytorium, ustaw ograniczenie liczby tokenów na sesję oraz przechowuj zapisy obok plików testowych, aby późniejsze zmiany modeli pozostały porównywalne.
Podczas pracy nad etapem 0 notatki dotyczącej wzmocnienia bezpieczeństwa najpierw zapisz warunki działania: wymagane dane wejściowe, sygnał sukcesu oraz to, co się dzieje w przypadku częściowego awarii. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Wolimy małe, testowalne jednostki niż rozbudowane skrypty. Gdy jakiś krok zawiedzie, awaria powinna wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji.
Szczegół wzmocnienia 0/631: zmierz czas wykonywania, klasę błędu oraz zużycie tokenów dla tej notatki, a następnie zdecyduj, czy zachować zmianę na podstawie ustalonego zestawu pytań, a nie jedynie anegdoty.
Etap 0 notatki o wzmocnieniach działa najlepiej, gdy jest traktowany jako mierzalna powierzchnia do analizy. Zapisz jeden idealny przepis działania, jeden przypadek awarii oraz notatkę o cofnięciu zmiany przed rozszerzeniem zakresu. Utrzymuj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą audytować bez konieczności przeglądania całej struktury.
Szczegół wzmocnienia 0/650: zmierz czas wykonywania, klasę błędu oraz zużycie tokenów dla tej notatki, a następnie zdecyduj, czy zachować zmianę na podstawie ustalonego zestawu pytań, a nie jedynie anegdoty.
Dla pierwszego etapu ulepszeń związanych z wzmocnieniem bezpieczeństwa należy określić dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy preferować małe, łatwe do przetestowania jednostki nad rozbudowanymi skryptami. Gdy dany krok zawiedzie, powód awarii powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowany proces.
Szczegół 1/650 dotyczący wzmocnienia bezpieczeństwa: zmierz czas wykonywania, klasę błędu oraz zużycie tokenów dla tego punktu, a następnie zdecyduj, czy zachować zmianę na podstawie ustalonego zestawu pytań, a nie jedynie informacji anegdotycznych.
Literatura pokrewna
- Praktyczne notatki: Buduj czy kup? Jak zespoły SaaS powinny podchodzić do infrastruktury MCP — Szczegółowy przewodnik po Praktycznych notatkach: Buduj czy kup? Jak zespoły SaaS powinny podchodzić do infrastruktury MCP: umowy, sprawdzenia oraz miejsca na kod do wstawienia dla zespołów wdrażających ten wzorzec.
- Praktyczne notatki: WebMCP: Moje trudności architektoniczne i gdzie myślę, że to może pójść — Szczegółowy przewodnik po Praktycznych notatkach: WebMCP: Moje trudności architektoniczne i gdzie myślę, że to może pójść: umowy, sprawdzenia oraz miejsca na kod do wstawienia dla zespołów wdrażających ten wzorzec.