Схема інструменту MCP змінилася. Ваш агент цього не помітив.

Виклик вашого інструменту не завершився збоєм. Він повернув статус-код 200 та валідний JSON.

Але він спрацював за невірним контрактом. Три дні тому upstream-сервер перейменував одне поле. Ваш агент продовжував надсилати стару назву. Сервер тихо її проігнорував. Результат повернувся порожнім. Помилки не виникло. Ніхто не помічав цього протягом тижня.

Це «тиха помилка». Не той гучний вид, коли логи стають червоними. А такий, коли сервер усміхається у відповідь, але дані невірні.

MCP-сервери можуть змінювати контракт інструменту між викликами. Вони можуть перейменувати параметр або змінити опис поля. Ці зміни часто залишаються структурно валідними. Валідація JSON проходить успішно. Сервер відповідає кодом 200. Ваш агент діє на основі невірних даних без жодної помилки.

Виправлення просте: • Зафіксуйте SHA-256 хеш кожного контракту інструменту. • Включіть у цей хеш і схему, і опис. • Перевіряйте хеш перед кожним викликом. • Зупиняйте виклик, якщо контракт змінився (drift).

Ми зосереджуємося на тому, чи відповідає інструмент. Ми перевіряємо статус-коди. Ми встановлюємо таймаути. Ми повторюємо запити при помилках 5xx. Майже ніхто не перевіряє, чи не змінився контракт у проміжку між моментом, коли агент дізнався про схему, і моментом, коли він зробив виклик.

MCP-сервер надає доступ до інструментів через tools/list. Кожен інструмент має inputSchema та опис. Ваш агент зчитує це один раз на початку сесії.

Якщо сервер оновиться, він може:

  • Перейменувати параметр (наприклад, з query на q), залишаючи при цьому відкритими додаткові властивості. Старий параметр буде тихо проігноровано.
  • Змінити значення поля. Обмеження може змінитись із «max results» на «page index». Тип залишається цілим числом (integer), тому валідація проходить успішно.
  • Звузити перелік enum. Валідне значення може бути примусово приведено до нового значення за замовчуванням.

Специфікація MCP каже, що сервер МАЄ (SHOULD) сповіщати клієнта про зміну списку. Вона не каже, що він ПОВИНЕН (MUST). Багато серверів не надсилатимуть таке сповіщення. Навіть якщо надішлють, вони можуть не повідомити, що змінилася схема конкретного інструменту.

Припиніть покладатися лише на структурну валідацію. Вона не здатна помітити зміну змісту.

Ставтеся до своїх MCP-інструментів як до залежностей програмного забезпечення. Використовуйте підхід із lock-файлом. При першому контакті створіть SHA-256 хеш схеми та опису інструменту. Перед кожним викликом перераховуйте хеш. Якщо вони збігаються — продовжуйте. Якщо ні — зафіксуйте розбіжність і зупиніться.

Секрет у хешуванні опису. Якщо параметр змінюється з «max results» на «page index», схема виглядає так само. Але хеш зміниться, бо змінилися слова. Це дозволяє виявити семантичну розбіжність, яку пропускає валідація.

Не намагайтеся вгадати, коли контракт змінився. Не робіть повторних спроб наосліп. Зробіть паузу, залогуйте різницю та виправте контракт.

Source: https://dev.to/0012303/the-mcp-tool-your-agent-calls-changed-its-schema-it-didnt-notice-5g6m

Optional learning community: https://t.me/GyaanSetuAi