Усунення помилок Model Context Protocol Elicitation в автономному режимі Claude Code
Виклик інструментів Model Context Protocol із методом ctx.elicit() аварійно завершується в автономних сесіях Claude Code та пайплайнах CI. Перехід до опційних параметрів інструментів з інструкціями у docstring забезпечує безперебійне виконання автоматичних агентних завдань.
Чому це важливо
Оновіть інструменти серверів Model Context Protocol вже сьогодні, щоб запобігти падінню автоматизованих робочих процесів Claude Code через необроблені винятки.
TL;DR
- 01Фоновий запуск (claude -p) позбавлений зворотного транспортного каналу, тому ctx.elicit() викликає виняток замість повернення статусу відхилення.
- 02Використовуйте опційні параметри функції та детальний docstring, щоб модель передавала значення самостійно у фоновому режимі.
- 03У Python MCP SDK 2.3.0 замість FastMCP використовується MCPServer, а параметри схеми вимагають snake_case (requested_schema).
Ключові факти
- Перевірена версія Claude Code
- 2.1.310
- Перевірена версія Python MCP SDK
- 2.3.0
- Зміна в імпортах
- Клас FastMCP перейменовано на MCPServer у mcp.server.mcpserver
Пастка Elicitation у фонових сесіях
Під час розробки інструментів за допомогою Python SDK для Model Context Protocol (MCP) виклик ctx.elicit() використовується для запиту додаткових аргументів у користувача. Якщо в інтерактивному режимі все працює, то неінтерактивна команда claude -p спричиняє негайний збій:
Cannot send 'elicitation/create': this transport context has no back-channel for server-initiated requests.Оскільки автономне середовище не має користувацького інтерфейсу чи зворотного каналу зв'язку від сервера до клієнта, транспорт генерує виняток, повністю оминаючи логіку перевірки result.action != 'accept'.
Дворежимне рішення: параметри у схемі інструмента
Щоб інструмент працював як в інтерактивному чаті, так і у фонових скриптах CI/CD, обов'язкові змінні необхідно винести у сигнатуру функції як опційні параметри:
1. Задати параметр як опційний (environment: str | None = None). 2. Додати чіткий docstring: "Вкажіть environment; якщо пропущено, запит буде надіслано користувачеві". 3. Огорнути виклик ctx.elicit() у блок try/except. 4. У разі транспортного винятку повернути зрозумілий текст помилки, спонукаючи LLM викликати функцію повторно із заповненим аргументом.
Архітектурні деталі Python SDK 2.x
У версії Python MCP SDK 2.3.0 застарілий клас FastMCP замінено на from mcp.server.mcpserver import MCPServer. Крім того, поле передачі схеми в реалізації SDK використовує requested_schema (snake_case). Слід уникати загального перехоплення except Exception, оскільки воно приховує помилки формату схем та мережеві таймаути.
Спробуй за 2 хвилини
from mcp.server.mcpserver import MCPServer, Context
from pydantic import BaseModel, Field
class Target(BaseModel):
environment: str = Field(description="staging or production")
async def deploy(service: str, ctx: Context, environment: str | None = None) -> str:
"""Deploy a service. Pass `environment` (staging or production); if omitted, the user is asked."""
if not environment:
try:
r = await ctx.elicit(message=f"Deploy {service} where?", schema=Target)
if r.action != "accept":
return f"Cancelled ({r.action})."
environment = r.data.environment
except Exception:
return ("Error: no environment given and this client can't prompt the user. "
"Call again with environment='staging' or 'production'.")
return f"Deployed {service} to {environment}."python
✓ Коли використовувати
- Під час запуску Claude Code або MCP-агентів у фонових скриптах, cron-завданнях чи CI/CD пайплайнах.
- При проектуванні інструментів MCP, розрахованих як на роботу в чаті з людиною, так і на автоматичне виконання.
✕ Коли НЕ варто
- Не застосовуйте цей патерн для інструментів, що вимагають обов'язкового фізичного підтвердження через апаратні ключі безпеки.
- Не використовуйте його замість стандартної валідації параметрів, коли всі дані відомі заздалегідь.
Що зробити сьогодні
- Перевірте власні MCP-сервери на наявність прямих викликів ctx.elicit() без обробки винятків.
- Змініть сигнатури інструментів, додавши опційні параметри за замовчуванням зі значенням None та детальним docstring.
- Протестуйте автономний запуск за допомогою команди claude -p --mcp-config mcp.json перед інтеграцією в CI.