Главная / Статьи

Практические замечания: скрытые расходы на «просто добавьте .mcp.json»

Пошаговое руководство по практическим замечаниям: скрытые издержки использования формата «просто добавьте .mcp.json»: контракты, проверки и слоты для вставки кода для команд, использующих эту схему.

Издатель: REACTAPP.TOP9 мин чтения2126 слов

Источники: The hidden cost of ‘just add an .mcp.json’

В следующих примечаниях описывается практический подход к решению проблемы, связанной с «скрытыми затратами от простого добавления файла .mcp.json». Основное внимание уделяется контрактам, проверкам и местам для вставки кода, а не мотивирующим аспектам. На этапе обзора сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и последствия частичной неудачи. Такой список поможет сохранять честность при последующих изменениях кода. Рядом с функциональными результатами записывайте время выполнения и стоимость токенов или запросов. Отображение затрат с самого начала предотвращает неожиданные расходы при переходе с демо-среды в общедоступные среды.

Как схемы инструментов влияют на вашу работу

Схемы инструментов типа How work best when treated as a measurable surface. Сначала необходимо собрать один эталонный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию, прежде чем расширять объём работы. Конфигурацию следует хранить отдельно от кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Инструменты с узкими схемами и чёткими метками о побочных эффектах должны быть представлены открыто. Хостам необходимо знать, какие вызовы изменяют состояние, прежде чем они автоматически одобрят их выполнение.

{
  "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"]
  }
}

Базовый налог, которого нельзя избежать

Основная налоговая ставка, которую вы используете, работает лучше всего, если рассматривать её как измеримую величину. Соберите один пример успешной работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объёма работ. Документируйте одновременно путь успешного выполнения и путь восстановления. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не этапом последующей доработки. Обеспечьте доступ к инструментам с узкими схемами и чёткими метками побочных эффектов. У операторов должна быть информация о том, какие вызовы изменяют состояние, прежде чем они автоматически одобрят операцию.

Реальные цифры: типичный файл .mcp.json

Этап работает наилучшим образом, когда его рассматривают как измеримую поверхность. Перед расширением объема работы соберите один идеальный пример выполнения, один случай сбоя и записку о возврате к предыдущему состоянию. Лучше использовать небольшие, тестируемые единицы вместо обширных скриптов. Когда какой-то шаг сбивается, причина сбоя должна указывать на конкретную ответственность, а не на запутанную цепочку операций. Используйте инструменты с узкими схемами и четкими метками о побочных эффектах. У операторов должна быть возможность узнать, какие вызовы изменяют состояние, прежде чем они автоматически одобрят действия. Этап работает наилучшим образом, когда его рассматривают как измеримую поверхность. Перед расширением объема работы соберите один идеальный пример выполнения, один случай сбоя и записку о возврате к предыдущему состоянию. Записывайте время выполнения, а также стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости на раннем этапе предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам.

{
  "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"]
    }
  }
}

Почему это наносит больший ущерб, чем позволяют предположить денежные затраты

На этапе определения причин более сильной боли необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Аутентифицируйтесь у шлюза и повторно авторизуйтесь на уровне обработки данных. Один только токен-носитель не является границей между тенантами.

1. Схемы инструментов конкурируют с вашим диалогом за одно и то же фиксированное время обработки.

На этапе соревнования схем инструментов необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Необходимо одновременно задокументировать успешный и аварийный сценарии работы. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки. Аутентификация происходит на шлюзе, а повторная авторизация — на уровне данных. Один только токен-носитель не является границей между тенантами.

2. Увеличение количества инструментов приводит к увеличению задержек и ошибкам при выборе.

Для улучшения функционала дополнительных инструментов необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Лучше использовать небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое шага причина должна быть связана с конкретной функцией, а не с запутанной структурой обработки данных. Аутентификация происходит на входе, а повторная авторизация — на уровне обработки данных. Одного только токена недостаточно для определения границ использования ресурсов. Для улучшения функционала дополнительных инструментов необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рядом с функциональными результатами следует записывать время выполнения, стоимость токенов или запросов. Отслеживание затрат на раннем этапе предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам.

3. Запуск сервера увеличивает задержку помимо затрат на токены.

При работе над этапом «Запуск сервера увеличивает задержку» сначала запишите условия контракта: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист помогает избегать ошибок при последующих изменениях кода. Храните конфигурацию отдельно от кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Храните в кэше стабильные инструкции системы и схемы инструментов. Пересылка одинаковых данных является распространенной причиной ненужных затрат.

Как Claude Code уже снижает этот риск

При работе над разделом «Как Claude Code уже находится на этапе подготовки» сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и что происходит при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Документируйте одновременно успешный сценарий работы и сценарий восстановления. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки. Фиксируйте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Без такой записи отладка циклов агента занимает часы.

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
...

Что вы можете с этим сделать

При работе над этапом «Что вы можете сделать» сначала запишите условия контракта: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой список помогает сохранять честность при последующих изменениях кода. Предпочитайте небольшие, тестируемые единицы кода большим скриптам. Когда какой-то шаг не срабатывает, причина должна быть связана с одной конкретной функцией, а не с запутанной цепочкой операций. Записывайте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Без такой информации отладка занимает часы.

1. Проверьте стоимость схемы вашего инструмента

При работе над этапом «Проверка инструмента» сначала запишите условия контракта: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Укажите названия элементов, определите критерии успешности и не допускайте молчаливого частичного выполнения задачи. Записывайте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Без такой записи отладка занимает гораздо больше времени.

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. Используйте конфигурации проектного масштаба

При работе над этапом «2. Использование конфигураций, ограниченных объемом проекта», сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список помогает избегать ошибок при последующих изменениях кода. Рядом с результатами функционирования записывайте время выполнения, стоимость токенов или запросов. Отслеживание затрат с самого начала предотвращает неожиданные счета при переходе с демо-среды в общедоступные среды. Для каждого вызова фиксируйте название инструмента, хэш аргументов, время задержки и результат. Без такой информации отладка занимает гораздо больше времени.

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

3. Отдавайте предпочтение серверам, которые предоставляют меньше инструментов с четко определенным назначением

При работе над пунктом «3. Выбор серверов для предварительной обработки» сначала запишите условия работы: необходимые параметры входных данных, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Храните конфигурацию отдельно от кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код.

4. Если вы разрабатываете клиент, реализуйте отложенную загрузку

При работе над четвертым этапом реализации отложенной загрузки сначала запишите спецификацию: необходимые входные данные, сигнал о успехе и действия при частичной неудаче. Такой список поможет сохранять честность при последующих изменениях кода. Задокументируйте одновременно успешный сценарий и сценарий восстановления. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки. Фиксируйте имя инструмента, хеш аргументов, время задержки и результат каждого вызова. Без такой записи отладка агента занимает часы.

// 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,
});

Вердикт

На этапе «Вердикт» сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список помогает сохранять честность при последующих изменениях кода. Предпочитайте небольшие, тестируемые модули большим скриптам. Если какой-то шаг не сработает, причина должна быть связана с конкретной функцией, а не с запутанной цепочкой операций. Записывайте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Без такой информации отладка занимает гораздо больше времени. На этапе «Вердикт» сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список помогает сохранять честность при последующих изменениях кода. Рядом с функциональными результатами фиксируйте время выполнения и стоимость токенов или запросов. Отслеживание затрат с самого начала предотвращает неожиданные расходы при переходе с демо-среды в общедоступные.

Чек-лист операций

На этапе операционного чек-листа необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии.

Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Укажите названия элементов, определите критерии успеха и не допускайте безответственного частичного выполнения задачи.

Аутентифицируйтесь у шлюза и повторно авторизуйтесь на уровне данных. Один только токен-носитель не является границей тенантности.

Напишите краткий руководство: как обновлять ключи, как опустошать очередь, как откатывать последнюю загрузку данных.

Записывайте время выполнения операций, стоимость токенов или запросов вместе с функциональными результатами. Отслеживание затрат заранее помогает избежать неожиданных счетов при переходе с демо-среды в общедоступные среды.

Аутентифицируйтесь у шлюза и повторно авторизуйтесь на уровне данных. Один только токен-носитель не является границей тенантности.

Перед повышением версии стека заморозьте текущие версии, сделайте копию критически важных записей для ключевых этапов и убедитесь, что известны шаги возврата к предыдущей версии. В совместных средах необходимы ограничения по частоте запросов, проверки тенантности и четко определенный ответственный за обновление секретов. Лучше выбирать надежность, чем креативные одноразовые демонстрации.

Примечание для версии 06d5cd938e01: не храните ключи поставщика в репозитории, установите лимит на количество токенов за сессию и сохраняйте записи рядом с фиксами для оценки, чтобы позже можно было сравнивать результаты работы моделей.