Strona główna / Artykuły

Uwagi praktyczne: Ukryte koszty „po prostu dodaj .mcp.json”

Krok po kroku praktyczne wskazówki: ukryte koszty dodania pliku .mcp.json – umowy, sprawdzenia oraz miejsca na kod do wklejenia dla zespołów stosujących ten wzorzec.

Wydawca: REACTAPP.TOP9 min czytania2126 słów

Źródła: The hidden cost of ‘just add an .mcp.json’

Poniższe notatki przedstawiają praktyczny plan działania dotyczący tematu „Ukryte koszty dodania pliku .mcp.json”. Nacisk kładziony jest na umowy, sprawdzania oraz miejsca zastępcze dla kodu, a nie na motywacyjne aspekty. Podczas przechodzenia przez etap przeglądu, 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 wykonywania operacji oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega nieoczekiwanym rachunkom, gdy przechodzi się od wersji demonstracyjnej do środowisk współdzielonych.

Jak schematy narzędzi wchodzą do twojego kontekstu

Schematy narzędzi typu How enter stage funkcjonują najlepiej, gdy traktuje się je jako mierzalną powierzchnię. Zapisz jeden idealny przepis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmian, zanim rozszerzysz zakres. Przechowuj 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. Ujawniaj narzędzia o wąskich schematach oraz z wyraźnymi etykietami efektów ubocznych. Hostowie muszą wiedzieć, które wywołania zmieniają stan, zanim automatycznie je zatwierdzą.

{
  "name": "slack_send_message",
  "description": "Send a message to a Slack channel or user",
  "inputSchema": {
    "type": "object",
    "properties": {
      "channel": {
        "type": "string",
        "description": "Channel ID or name to send the message to"
      },
      "text": {
        "type": "string",
        "description": "The message content to send"
      },
      "thread_ts": {
        "type": "string",
        "description": "Optional thread timestamp to reply in a thread"
      }
    },
    "required": ["channel", "text"]
  }
}

Bazowy podatek, którego nie da się uniknąć

Baza podatkowa, którą stosujesz, działa najlepiej, gdy traktuje się ją jako mierzalną powierzchnię. Zapisz jeden udany przypadek, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań przed rozszerzeniem zakresu. Zdokumentuj zarówno ścieżkę prawidłowego działania, jak i ścieżkę naprawczą. Próby ponownych działań, kontrolne punkty ludzkie oraz obsługa wiadomości błędowych stanowią część produktu, a nie elementy dodawane później. Używaj narzędzi z wąskimi schematami oraz wyraźnymi etykietami opisującymi efekty uboczne. Hostowie muszą wiedzieć, które wywołania zmieniają stan, zanim dokonają automatycznej aprobaty.

Prawdziwe liczby: typowy plik .mcp.json

Prawdziwe liczby: etap funkcjonuje najlepiej, gdy traktowany jest jako mierzalna powierzchnia. Zapisz jeden idealny zapis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres. Wolno preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy jakiś krok zawiedzie, awaria powinna wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Używaj narzędzi o wąskich schematach oraz z wyraźnymi etykietami efektów ubocznych. Hostowie muszą wiedzieć, które wywołania zmieniają stan, zanim automatycznie je zatwierdzą. Prawdziwe liczby: etap funkcjonuje najlepiej, gdy traktowany jest jako mierzalna powierzchnia. Zapisz jeden idealny zapis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres. Zapisuj czasy wykonywania oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy proces przechodzi z wersji demonstracyjnej do środowisk współdzielonych.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/projects"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

Dlaczego to szkodzi bardziej, niż sugeruje koszt w dolarach

Na etapie zastanawiania się, dlaczego ból jest silniejszy, 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 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ę przy bramie wejściowej, a ponowna autoryzacja – na poziomie przetwarzania danych. Sam token nośny nie stanowi granicy między poszczególnymi użytkownikami.

1. Schematy narzędzi konkurują z twoją rozmową o to samo ograniczone okno czasowe.

W fazie konkurencji schematów narzędzi nr 1 należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy udokumentować zarówno prawidłowy przebieg procesu, jak i ścieżkę naprawczą. Próby ponownych działań, kontrolne punkty ludzkie oraz obsługa wiadomości błędnych stanowią część produktu, a nie elementy dodawane później. Autoryzacja powinna odbywać się przy bramce, a ponowna autoryzacja – na poziomie warstwy danych. Sam token nośny nie stanowi granicy między poszczególnymi użytkownikami.

2. Więcej narzędzi zwiększa opóźnienia i błędy przy wyborze.

Dla kolejnych dwóch narzędzi w fazie rozwoju 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. Należy preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy dany krok zawiedzie, powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Uwierzytelniaj się przy bramie wejściowej, a ponownie autoryzuj na poziomie warstwy danych. Sam token nie stanowi granicy między poszczególnymi użytkownikami. Dla kolejnych dwóch narzędzi w fazie rozwoju 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. Zapisuj czas trwania operacji oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy proces przechodzi z środowiska demonstracyjnego do współdzielonych środowisk.

3. Uruchamianie serwera powoduje opóźnienie dodatkowe poza kosztem tokena.

Gdy przechodzisz przez etap „Uruchamianie serwera powoduje opóźnienie”, 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. Przechowuj 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. Zachowuj w pamięci podręcznej stabilne instrukcje systemowe oraz schematy narzędzi. Ponowne wysyłanie identycznego prefiksu jest częstą przyczyną marnotrawstwa zasobów.

Jak Claude Code już to łagodzi

Gdy pracujesz nad rozdziałem „Jak Claude Code już przechodzi do kolejnego etapu”, 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. Zdokumentuj zarówno ścieżkę prawidłowego działania, jak i ścieżkę naprawczą. Próby ponowne, kontrola przez ludzi oraz obsługa wiadomości błędowych są częścią produktu, a nie elementem późniejszej dopracowywania. Zapisuj nazwę narzędzia, hash argumentów, opóźnienie oraz wynik każdej wywołania. Bez takich informacji debugowanie pętli agenta marnuje godziny.

The following deferred tools are now available via ToolSearch.
Their schemas are NOT loaded - calling them directly will fail
with InputValidationError. Use ToolSearch with query
"select:<name>[,<name>...]" to load tool schemas before calling them:

mcp__plugin_slack_slack__slack_send_message
mcp__plugin_slack_slack__slack_read_channel
mcp__plugin_github_github__list_recent_viewer_prs
...

Co możesz z tym zrobić

Gdy przechodzisz przez etap „Co możesz zrobić”, 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. Wolę małe, testowalne jednostki niż rozbudowane skrypty. Gdy jakiś krok się nie powiedzie, błąd powinien wskazywać na jedną konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Zapisuj nazwę narzędzia, hash argumentów, opóźnienie oraz wynik każdego wywołania. Bez takich informacji debugowanie zajmuje godziny.

1. Sprawdź koszt schematu swojego narzędzia

Gdy przechodzisz przez etap 1 „Audyt 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. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy poszczególnym elementom, zdefiniuj kryteria sukcesu i odrzuć możliwość cichego, częściowego ukończenia zadania. Zapisuj nazwę narzędzia, hash argumentów, czas reakcji oraz wynik każdego wywołania. Bez takich informacji debugowanie zajmuje godziny.

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-github"],
  env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN! }
});

const client = new Client({ name: "audit", version: "1.0.0" });
await client.connect(transport);

const { tools } = await client.listTools();
console.log(`Server exposes ${tools.length} tools`);

let totalTokens = 0;
for (const tool of tools) {
  const schemaStr = JSON.stringify(tool);
  // ~3-4 chars per token for JSON; this is a rough lower bound
  const estimatedTokens = Math.ceil(schemaStr.length / 3.5);
  totalTokens += estimatedTokens;
  console.log(`  ${tool.name}: ~${estimatedTokens} tokens`);
}
console.log(`\nEstimated context cost: ~${totalTokens} tokens/turn`);
console.log(`(For exact counts, use Anthropic's token counting API)`);

await client.close();

2. Używaj konfiguracji skrojonych pod projekt

Gdy przechodzisz przez etap 2 „Używanie konfiguracji skrojonych pod projekt”, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co się dzieje w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Obok wyników funkcjonalnych zapisz czas trwania oraz koszt tokena lub zapytania. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy ścieżka przechodzi z wersji demonstracyjnej do środowisk współdzielonych. Zapisuj nazwę narzędzia, hash argumentów, opóźnienie oraz wynik każdego wywołania. Bez takich informacji debugowanie agenta może trwać godzinami.

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"]
    }
  }
}

3. Wolij serwery, które oferują mniej narzędzi o dobrze określonym zakresie działania

Gdy zajmujesz się punktem 3 „Wybierz serwery do przechowywania wstępnego stanu”, 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. Przechowuj 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.

4. Zaimplementuj opóźnione ładowanie, jeśli budujesz klienta

Gdy przechodzisz przez 4 etapy wdrażania opóźnionego ładowania, 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. Zdokumentuj zarówno ścieżkę prawidłowego działania, jak i ścieżkę naprawczą. Próby ponowne, kontrola przez ludzi oraz obsługa wiadomości błędnych stanowią część produktu, a nie elementy dopinane później. Zapisuj nazwę narzędzia, hash argumentów, opóźnienie oraz wynik każdej wywołania. Bez tego śladu debugowanie agenta trwa godzinami.

// What goes into the system prompt (cheap, ~5-8 tokens per tool):
const toolDirectory = tools.map(t => t.name);
const systemPrompt = `Available tools (use ToolSearch to load): ${toolDirectory.join(", ")}`;

// What goes into the API request's tools parameter (expensive):
// Only include tools the model has explicitly requested via ToolSearch
const activeTools: ToolSchema[] = [];

// When the model calls ToolSearch("slack_send_message"):
function loadTool(name: string) {
  const schema = cachedSchemas.get(name);
  if (schema) activeTools.push(schema);
}

// API call only pays for activeTools, not all 200
const response = await anthropic.messages.create({
  tools: activeTools,  // 1-4 tools, not 200
  system: systemPrompt,
  messages: conversation,
});

Werdykt

Podczas przechodzenia przez etap The verdict, 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. Wolno preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy jakiś krok się nie powiedzie, błąd powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Zapisuj nazwę narzędzia, hash argumentów, opóźnienie oraz wynik każdego wywołania. Debugowanie bez takich informacji marnuje godziny. Podczas przechodzenia przez etap The verdict, 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. Zapisuj czasy wykonywania oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy proces przechodzi z środowiska demonstracyjnego do wspólnych środowisk.

Lista kontrolna operacyjna

W fazie listy kontrolnej operacyjnej należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie wykonać ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu.

Traktuj tę fazę jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nazwij poszczególne elementy, zdefiniuj kryteria sukcesu i odrzuć ciche, częściowe ukończenie zadania.

Zaloguj się przy bramie dostępu i ponownie uzyskaj uprawnienia na poziomie warstwy danych. Sam token nie stanowi granicy między poszczególnymi środowiskami.

Napisz krótki przewodnik: jak rotować klucze, jak opróżnić kolejkę z zadań, jak cofnąć ostatnie operacje importu.

Zapisz czasy wykonywania zadań 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.

Zaloguj się przy bramce i ponownie zatwierdź dostęp na poziomie warstwy danych. Sam token nośny nie stanowi granicy między usługami.

Zanim zaktualizujesz całą strukturę, zamroź wersje oprogramowania, utwórz dokładny zapis procesu dla kluczowych etapów oraz potwierdź kroki odwracania zmian. Środowiska współdzielone wymagają ograniczeń szybkości, weryfikacji przynależności do konkretnych usług oraz wyraźnego właściciela odpowiedzialnego za rotację haseł. Wolisz przewidywalną niezawodność niż pomysłowe, jednorazowe demonstracje.

Uwaga dotycząca pliku 06d5cd938e01: trzymaj klucze dostawcy poza repozytorium, ustaw ograniczenie liczby tokenów na sesję oraz przechowuj zapisy obok plików testowych, aby późniejsze zmiany modeli pozostały porównywalne.

Literatura pokrewna