بخش 7.3 · اکوسیستم

کار با MCP از طریق langchain.mcp

MCP with langchain.mcp

فهرست مطالب
  1. پکیج و هشدار بتای آن
  2. از سرور تا ایجنت
  3. آرگومان رشته‌ای مقصد حتماً باید URL باشد
  4. خطاها، تایم‌اوت‌ها و کرش کردن سرور
  5. هزینه‌ی فراخوانی
  6. استخراج ورودی، خطاهای ساختاریافته و گزارش پیشرفت

کلاس MCPAdapter ابزارهای سرور MCP را به ابزارهای LangChain تبدیل می‌کند، رشته‌هایی را که URL نباشند رد می‌کند، و با کرش کردن سرور، کل اجرا متوقف می‌شود.

فرض کنید یک سرور MCP برای سامانه رهگیری باگ‌هایتان (issue tracker) پیدا کرده‌اید و می‌خواهید ابزارهای آن را وارد ایجنت (agent) خود کنید. در تمام مثال‌هایی که می‌بینید، MultiServerMCPClient از پکیج langchain_mcp_adapters ایمپورت شده است. شما این پکیج را در کنار langchain[mcp] نصب می‌کنید، و pip نسخه mcp را برای هماهنگی با این تطبیق‌دهنده (adapter) قدیمی به نسخه‌ای پایین‌تر بازمی‌گرداند (downgrade می‌کند).

با پایان این بخش، می‌توانید ابزارهای MCP را با langchain.mcp در یک ایجنت بارگذاری کنید. همچنین می‌توانید پیش‌بینی کنید که خطای یک ابزار، کند بودن آن، یا کرش کردن سرور چه تأثیری روی اجرا می‌گذارد. علاوه بر این، می‌توانید تایم‌اوتی را که تطبیق‌دهنده ندارد تنظیم کنید، و به سروری که درخواست ورودی دارد پاسخ بدهید.

پکیج و هشدار بتای آن

تطبیق‌دهنده MCP (یا MCP adapter): کلاس MCPAdapter در پکیج langchain.mcp. این کلاس از طریق FastMCP به یک سرور MCP وصل می‌شود و ابزارهای آن سرور را در قالب ابزارهای LangChain تحویل می‌دهد.

نسخه 1.4.0 فریم‌ورک langchain ماژول langchain.mcp را جایگزین پکیج بایگانی‌شده‌ی langchain-mcp-adapters کرد {{docs oss/python/releases/changelog}}. آن را با افزونه اختیاری langchain[mcp] نصب می‌کنید که به fastmcp نسخه 4.0.11 یا بالاتر نیاز دارد. در محیط تست این درس، پکیج fastmcp با نسخه 4.2.0 و mcp با نسخه 2.3.0 رفع وابستگی (resolve) شدند. اولین باری که آن را ایمپورت می‌کنید، در هر فرایند (process) یک بار هشدار زیر نمایش داده می‌شود:

ایمپورت کردن langchain.mcp capture/out/40-mcp.txt
warning LangChainBetaWarning: `langchain.mcp` is in beta. It is actively being worked on, so the API may change.

این پکیج سه نام ارائه می‌دهد: MCPAdapter، MCPToolArtifact و as_langchain_tool. تطبیق‌دهنده‌ی قدیمی را در همان محیط نصب نکنید. نسخه 0.3.2 پکیج langchain-mcp-adapters به نسخه‌ای از mcp کمتر از 2.0 نیاز دارد {{code langchain-mcp-adapters pyproject.toml}}، در حالی که fastmcp نسخه 4.2.0 نیازمند mcp نسخه 2.3.0 است. در محیط مربوط به تطبیق‌دهنده‌ی قدیمی، ابزار تفکیک وابستگی‌ها نسخه mcp 1.30.0 را انتخاب کرد.

از سرور تا ایجنت

کیت آموزشی ما یک سرور FastMCP با نام calc درون همان فرایند می‌سازد و شیء سرور را به MCPAdapter ارسال می‌کند. یک سرور درون‌فرایندی (in-process) نیازی به پورت شبکه و زیرفرایند (subprocess) ندارد. متد list_tools() به ازای هر ابزار MCP، یک ابزار LangChain برمی‌گرداند:

یکی از سه ابزار list_tools capture/out/40-mcp.txt
  {
    "name": "multiply",
    "description": "Multiply two integers.",
    "args": {
      "a": {
        "type": "integer"
      },
      "b": {
        "type": "integer"
      }
    },
    "response_format": "content_and_artifact"
  },

ابزار اول. divide و stats حذف شده‌اند.

مقدار response_format در تمام ابزارها برابر با content_and_artifact تنظیم شده است. مدل فقط محتوا (content) را می‌بیند که فهرستی از بلوک‌های متنی است. در یک فراخوانی موفق، نتیجه‌ی ساختاریافته‌ی سرور درون دست‌سازه (artifact) باقی می‌ماند؛ جایی که کد شما می‌تواند آن را بخواند ولی مدل به آن دسترسی ندارد:

پیام ToolMessage مربوط به multiply capture/out/40-mcp.txt
    "type": "ToolMessage",
    "content": [
      {
        "type": "text",
        "text": "42",
        "id": "lc_<uuid-5>"
      }
    ],
    "name": "multiply",
    "id": "<uuid-6>",
    "tool_call_id": "<uuid-2>",
    "status": "success",
    "artifact": {
      "structured_content": {
        "result": 42
      }
    }

ماژول langchain.mcp هیچ رابط برنامه‌نویسی‌ای (API) برای منابع (resources) یا پرامپت‌های (prompts) سرور MCP ندارد. راهنمای مهاجرت هم هر دو مورد را جزو موارد پشتیبانی‌نشده آورده است {{docs oss/python/migrate/langchain-mcp-adapters}}. در کیت تست، منبعی را از طریق adapter.client (که همان کلاینت FastMCP در لایه‌ی زیرین است) خواندیم و مقدار calc server: multiply, divide, stats را گرفتیم.

آرگومان رشته‌ای مقصد حتماً باید URL باشد

مقصد (Target): اولین آرگومان ورودی کلاس MCPAdapter. این آرگومان می‌تواند یک URL با پروتکل http یا https، یک شیء Path به یک اسکریپت، یا بستر انتقال (transport) در FastMCP باشد. همچنین می‌تواند یک سرور درون‌فرایندی FastMCP، یک دیکشنری MCPConfig، یا یک نمونه از fastmcp.Client باشد.

نوع داده‌ی مقصد، بستر انتقال را مشخص می‌کند. ارسال Path اسکریپت را به عنوان زیرفرایند روی ورودی/خروجی استاندارد (stdio) اجرا می‌کند. نوع داده‌ی str حتماً باید یک URL با پروتکل http یا https باشد. ارسال هر رشته‌ی دیگری هنگام ساخت تطبیق‌دهنده باعث خطا می‌شود:

رشته‌ای که نام یک فایل است capture/out/40-mcp.txt
MCPAdapter('server.py'):

raised builtins.ValueError: MCP target 'server.py' is not a valid URL. To run a local MCP server over stdio, ask for it explicitly with `Path('server.py')`, a `fastmcp` transport, or an `MCPConfig` — a bare string is read as a URL so that it cannot silently become a subprocess.

بررسی این موضوع با تابع _validate_url_target انجام می‌شود که پیش از ساخت کلاینت FastMCP توسط تطبیق‌دهنده اجرا می‌گردد {{code libs/langchain_v1/langchain/mcp/adapter.py}}. این تابع حتی URL با پیشوند file:// را هم رد می‌کند، چون طرحواره‌ی (scheme) آن http یا https نیست.

در مستندات MCP هشدار داده شده است که اگر رشته‌ای نام یک فایل موجود با پسوند .py یا .js باشد، آن فایل به عنوان زیرفرایند اجرا خواهد شد {{docs oss/python/langchain/mcp}}. این رفتار مربوط به fastmcp.Client است و همان پاراگراف تأکید می‌کند که MCPAdapter چنین رشته‌ای را نمی‌پذیرد. نتایج اجرای ما هر دو نکته را تأیید کرد.

روی macOS، سه رشته‌ی مختلف مربوط به یک اسکریپت سرور موجود را به MCPAdapter دادیم: مسیر نسبی، مسیر مطلق، و یک URL با پیشوند file://. در هر سه حالت خطای ValueError رخ داد و هیچ فرایندی اجرا نشد. اما ارسال همان مسیر نسبی به fastmcp.Client اسکریپت را اجرا کرد. اسکریپت آزمایشگاهی ما هشدارها را فیلتر کرده بود، بنابراین هشداری ثبت نشد. در نتیجه این خطر فقط زمانی وجود دارد که خودتان مستقیماً یک fastmcp.Client از روی رشته بسازید و سپس آن را به تطبیق‌دهنده بدهید.

مقصدی که از فایل تنظیمات یا از طرف یک مدل بیاید، در قالب رشته است. تا زمانی که آن را به صورت رشته نگه دارید، تطبیق‌دهنده فقط از طریق HTTP به آن دسترسی پیدا می‌کند. برای اجرای سرور محلی، در کد خودتان صریحاً بنویسید: Path("server.py").

خطاها، تایم‌اوت‌ها و کرش کردن سرور

خطای ابزار MCP (یا MCP tool error): نتیجه‌ی فراخوانی ابزار است که در آن isError برابر با true باشد. سرور FastMCP این وضعیت را زمانی ارسال می‌کند که ابزار با خطای ToolError یا هر استثنای (exception) دیگری متوقف شود.

تطبیق‌دهنده خطای ابزار را به یک ToolMessage با وضعیت (status) برابر با error تبدیل می‌کند {{code libs/langchain_v1/langchain/mcp/tools.py}}. مدل پیام متنی ارسال‌شده از سرور را می‌خواند و روند اجرا ادامه می‌یابد. در اینجا، مدل نتیجه‌ی هر فراخوانی را گزارش داد و اعلام کرد که تقسیم با خطای division by zero مواجه شده است. در کیت تست ما، مدل Qwen3 4B در یک پاسخ واحد ابزارهای multiply، divide و stats را فراخوانی کرد. اجرای divide با مخرج صفر خطای ToolError داد:

تبدیل خطای ابزار به یک ToolMessage خطا capture/out/40-mcp.txt
    "type": "ToolMessage",
    "content": [
      {
        "type": "text",
        "text": "division by zero",
        "id": "lc_<uuid-7>"
      }
    ],
    "name": "divide",
    "id": "<uuid-8>",
    "tool_call_id": "<uuid-3>",
    "status": "error"

اما قطعی بستر انتقال وضعیت متفاوتی دارد؛ از جنس ToolException نیست، بنابراین از مدیریت خطا عبور می‌کند و باعث پرتاب استثنا به بیرون و توقف اجرای برنامه می‌شود. مستندات هم همین را می‌گوید: خطای سرور به دست مدل می‌رسد، اما خرابی بستر انتقال یا نشست (session) باعث توقف برنامه با پرتاب استثنا می‌شود {{docs oss/python/langchain/mcp/tools}}. از آنجا که کیت ما نمی‌تواند یک سرور درون‌فرایندی را کرش کند، بقیه‌ی حالت‌ها را با سروری واقعی روی Mac آزمایش کردیم.

ما عملکرد هر سناریو را روی یک Mac با پردازنده Apple M1 Max، ده هسته، 64 گیگابایت رم، همراه با langchain 1.5.0 و fastmcp 4.2.0 اندازه‌گیری کردیم. سرور FastMCP روی stdio و پروتکل HTTP جریانی (Streamable HTTP) اجرا شد و هر سناریو را یک بار آزمایش کردیم. شکل نتیجه‌ی هر حالت را نشان می‌دهد.

تأثیر هر نوع شکست MCP بر یک اجراخطای ابزار به یک ToolMessage با وضعیت خطا تبدیل می‌شود و اجرا ادامه می‌یابد، اما ابزار کند فاقد مهلت زمانی است و کرش سرور، اجرا را متوقف می‌کند.
تأثیر هر نوع شکست MCP بر یک اجرا هفت سطر، هر کدام از یک حالت در سمت چپ به نتیجه آن در سمت راست. یک مقصد رشته‌ای که URL از نوع http یا https نباشد خطای ValueError صادر می‌کند و چیزی را اجرا نمی‌کند. ابزاری که isError را گزارش کند و ابزاری که یک استثنای پایتونی صادر کند، هر دو به یک ToolMessage با وضعیت خطا تبدیل می‌شوند و اجرا ادامه می‌یابد. یک ابزار کند با کلاینت پیش‌فرض پس از 2.0 ثانیه پاسخ می‌دهد، زیرا تطبیق‌دهنده مهلت زمانی ندارد. یک FastMCP Client با timeout=1 بعد از 1.0 ثانیه خطای MCPError: timed out صادر می‌کند. کرش سرور روی stdio خطای MCPError: Connection closed صادر کرده و اجرا را متوقف می‌کند، و فراخوانی بعدی دوباره سرور را اجرا می‌کند. کرش سرور روی HTTP در حین فراخوانی RemoteProtocolError صادر می‌کند و اجرای ایجنت و فراخوانی‌های بعدی پس از آن در اتصال ناموفق می‌شوند، زیرا چیزی دوباره سرور را اجرا نمی‌کند. حالت آنچه اجرا دریافت می‌کند MCPAdapter('server.py') رشته‌ای که URL نیست خطای ValueError، بدون اجرا رد شدن هنگام ساخت شیء ابزار isError را گزارش می‌دهد ToolError در سرور ToolMessage، وضعیت خطا اجرا ادامه می‌یابد استثنا در ابزار RuntimeError در سرور ToolMessage، وضعیت خطا اجرا ادامه می‌یابد ابزار کند، کلاینت پیش‌فرض slow(2) waits 2.0 s ToolMessage، وضعیت موفقیت تطبیق‌دهنده timeout ندارد slow tool, Client(timeout=1) slow(5) over stdio or HTTP MCPError: مهلت تمام شد خطا پس از 1.0 ثانیه کرش سرور، stdio os._exit(3) mid-call MCPError: اتصال بسته شد توقف اجرا، فراخوانی بعد ری‌استارت می‌کند کرش سرور، HTTP os._exit(3) mid-call RemoteProtocolError سپس خطا در اتصال رخ می‌دهد از مک، یک بار اجرای هر حالت، langchain 1.5.0 با fastmcp 4.2.0.
هر سطر را از حالت در سمت چپ به نتیجه در سمت راست بخوانید. سطرهای سبز به فراخوانی بعدی مدل می‌روند، سطر خاکستری منتظر می‌ماند و سطرهای سرخابی استثنا ایجاد می‌کنند. از capture/lab/summary/mcp-mac.json.
  • ابزاری که استثنا پرتاب می‌کند. بروز ToolError و یک RuntimeError ساده درون ابزار، در هر دو حالت تبدیل به یک ToolMessage با وضعیت error شد. درون create_agent، اجرا متوقف نشد و به فراخوانی بعدی مدل رفت.
  • ابزار کند. از آنجا که MCPAdapter فقط مقصد را ورودی می‌گیرد، هیچ تنظیمی برای تایم‌اوت ندارد {{code libs/langchain_v1/langchain/mcp/adapter.py}}. ابزاری که 2 ثانیه معطل کرد، پس از 2.0 ثانیه پاسخ داد. برای تعیین سقف زمانی، باید شیء fastmcp.Client(target, timeout=1) را بسازید و به تطبیق‌دهنده بدهید. در این صورت ابزاری که 5 ثانیه متوقف شده بود، پس از 1.0 ثانیه با خطای MCPError: Request 'tools/call' timed out متوقف شد، و فراخوانی بعدی با همان کلاینت بدون مشکل کار کرد.
  • کرش روی stdio. سرور در میانه‌ی فراخوانی تابع os._exit(3) را صدا زد. فراخوانی ظرف 0.01 ثانیه با خطای MCPError: Connection closed متوقف شد و اجرای ایجنت هم با همان استثنا پایان یافت. فراخوانی بعدی مجدداً سرور را راه‌اندازی کرد که 1.66 ثانیه زمان برد.
  • کرش روی HTTP. فراخوانی مستقیم باعث پرتاب استثنای RemoteProtocolError شد. اجرای ایجنت پس از آن و تمام فراخوانی‌های بعدی با خطای RuntimeError: Client failed to connect مواجه شدند، چون هیچ سازوکاری سرور HTTP را مجدداً برای شما اجرا نمی‌کند.

کرش کردن سرور کل اجرا را متوقف می‌کند و مدل هرگز پیام خطایی نمی‌بیند. همان‌طور که در بخش 3.4 آمده است، خطای مهارنشده در یک ابزار محلی هم دقیقاً به همین شیوه به اجرا پایان می‌دهد. اگر احتمال می‌دهید سرور متوقف شود، فراخوانی ایجنت را درون تلاش مجدد (retry) اختصاصی خودتان قرار دهید و اجرای آن را از روی چک‌پوینت (checkpoint) ادامه دهید. دقت کنید ممکن است سرور عملیات نوشتن را تمام کرده باشد اما قبل از ارسال پاسخ از کار بیفتد؛ بنابراین تلاش مجدد را فقط برای ابزارهای بی‌اثر در تکرار (idempotent) انجام دهید، یا یک کلید یکتایی تراکنش (idempotency key) پایدار همراه درخواست بفرستید.

هزینه‌ی فراخوانی

ما زمان اجرای 50 فراخوانی ابزار add را روی بسترهای انتقال مختلف در سیستم Mac، با نسخه 1.5.0 پکیج langchain اندازه گرفتیم. فایل خام خروجی، مقدار میانه و صدک 95ام هر دسته‌ی 50تایی فراخوانی را ذخیره می‌کند، نه هر درخواست را به طور مجزا. لپ‌تاپ هم‌زمان کارهای دیگری هم انجام می‌داد، بنابراین اعداد ثبت‌شده را به عنوان حد بالا (upper bound) در نظر بگیرید.

بستر انتقال میانه، تطبیق‌دهنده باز نشده صدک 95ام میانه، درون async with adapter صدک 95ام
stdio 9.5 ms 27.3 ms 5.9 ms 15.0 ms
پروتکل HTTP جریانی 24.7 ms 52.5 ms 10.7 ms 19.6 ms

سرور stdio تنها یک بار برای اجرای list_tools راه‌اندازی شد که 1.54 ثانیه زمان برد. تمام فراخوانی‌های بعدی از همان فرایند استفاده کردند. اگر ایجنت شما فراخوانی‌های زیادی انجام می‌دهد، اجرای آن را درون بلوک async with برای تطبیق‌دهنده بگذارید تا نشست کاری بین فراخوانی‌ها باز بماند.

تطبیق‌دهنده‌ی بایگانی‌شده رفتار متفاوتی دارد. ما langchain-mcp-adapters نسخه 0.3.2 را در محیطی جداگانه، همراه با mcp نسخه 1.30.0 و در ارتباط با همان سرور آزمایش کردیم:

راه‌اندازی سرور تحت langchain-mcp-adapters 0.3.2 capture/lab/T12-mcp-mac/03-adapters-launch-count.txt
Server launch markers in T12/_marks after the langchain-mcp-adapters 0.3.2 run: 57.
02 stdio: 1 (get_tools) + 3 single calls + 50 timed calls + crash + call after crash = 56 stdio launches, plus 1 HTTP server process = 57.
So langchain-mcp-adapters 0.3.2 starts one stdio subprocess per tool call (MultiServerMCPClient without an explicit session).

خطوط اول، سوم و چهارم شمارش.

در این حالت، هر فراخوانی روی stdio یک سرور جدید بالا می‌آورد و زمان میانه‌ی 50 فراخوانی به 1,887 میلی‌ثانیه رسید. روی بستر HTTP نیز کرش کردن سرور در میانه‌ی فراخوانی هیچ پاسخی برنمی‌گرداند و اسکریپت ما ناچار شد پس از 40 ثانیه آن را قطع کند. کدهای قدیمی که از آن تطبیق‌دهنده استفاده می‌کنند هر دو رفتار را به همراه دارند. آن‌ها را به langchain.mcp منتقل کنید.

استخراج ورودی، خطاهای ساختاریافته و گزارش پیشرفت

استخراج ورودی (Elicitation): درخواستی از طرف سرور MCP برای دریافت اطلاعات از کاربر در حین فراخوانی ابزار؛ مانند یک فرم با یک فیلد.

کلاس MCPAdapter تمام کلاینت‌هایی را که می‌سازد برای قابلیت استخراج ورودی آماده می‌کند. برای کلاینت‌هایی که خودتان ارسال می‌کنید، یک نسخه کپی با متد client.new() می‌سازد و آن را مجهز می‌کند. اگر کلاینت از قبل کنترل‌کننده‌ی (handler) اختصاصی elicitation_handler داشته باشد، تطبیق‌دهنده به آن دست نمی‌زند {{code libs/langchain_v1/langchain/mcp/adapter.py:173-187}}. وقتی سرور سؤالات خود را در قالب InputRequiredResult برمی‌گرداند، تطبیق‌دهنده آن‌ها را با استفاده از interrupt() در LangGraph از کاربر می‌پرسد {{code libs/langchain_v1/langchain/mcp/elicitation.py:311-364}}. به این ترتیب، یک ابزار MCP می‌تواند اجرای ایجنت را متوقف کند؛ درست مانند بازنگری در بخش 6.4.

ما این سناریوها را بدون مدل، روی Mac با نسخه‌های langchain 1.5.0، fastmcp 4.2.0، mcp 2.3.0 و langgraph 1.2.22 بررسی کردیم. هر حالت 3 بار در فرایندهای جداگانه اجرا شد و هر 3 اجرا نتیجه‌ی یکسانی دادند. سرور درون همان فرایند اجرا شد و 5 سناریو یک بار دیگر روی پروتکل HTTP جریانی نیز تست شدند. ابزار ask_name در سرور، یک فیلد فرم به نام name را درخواست کرد. تطبیق‌دهنده‌ی پیش‌فرض روی پروتکل نسخه 2026-07-28 توافق کرد.

درون create_agent همراه با InMemorySaver، فرایند اجرا با مقدار __interrupt__ متوقف شد و در وضعیت ایجنت، کلید next برابر با tools بود. مقدار وقفه (interrupt value) نام ابزار و جزئیات هر درخواست را در بر دارد:

مقدار وقفه برای یک استخراج ورودی MCP capture/lab/summary/mcp-edges-mac.json
       "value": {
        "requests": [
         {
          "key": "name",
          "message": "What is your name?",
          "mode": "form",
          "requested_schema": {
…
        "tool_name": "ask_name",
        "type": "mcp_elicitation"
       }

اسکیمای فیلد حذف شده است.

برای ادامه‌ی اجرا، یک دستور Command ارسال می‌کنید که در دیکشنری responses آن، کلید هر درخواست به پاسخ کاربر نگاشت شده است:

سه پاسخ به درخواست، و ازسرگیری capture/lab/T20-mcp-edges-mac/t20_mcp.py
                    action = {"accept": {"action": "accept", "content": {"name": "Ada"}}, "decline": {"action": "decline"}, "cancel": {"action": "cancel"}}
…
                    out = await agent.ainvoke(Command(resume={"responses": {"name": action[which]}}), cfg)
  • پذیرش (Accept). ابزار پیام موفقیت ToolMessage را همراه با پیام خوش‌آمدگویی برگرداند و روند اجرا چه در حالت درون‌فرایندی و چه روی HTTP به شکل عادی به پایان رسید.
  • رد کردن و انصراف (Decline and cancel). سرور عملیات مربوطه را دریافت کرد و پاسخ پیش‌فرض خود را داد: no name (decline) یا no name (cancel). تطبیق‌دهنده پس از انصراف کاربر، فراخوانی را قطع نکرد.
  • هزینه‌ی ازسرگیری اجرا. برای یک بار پاسخ به سؤال، سرور ابزار ask_name را 3 بار اجرا کرد. در زمان ازسرگیری، تطبیق‌دهنده فراخوانی ابزار را از همان دور اول مجدداً صدا می‌زند {{code libs/langchain_v1/langchain/mcp/elicitation.py:318-320}}. بنابراین اگر ابزاری قرار است از کاربر ورودی بگیرد، طوری طراحی‌اش کنید که قبل از شروع هر کاری، سؤالش را مطرح کند.
  • بدون چک‌پوینتر (Checkpointer). استریم خروجی مقدار __interrupt__ را تحویل داد و اجرا بدون هیچ استثنایی و بدون امکان ازسرگیری به پایان رسید.
  • خارج از گراف. فراخوانی مستقیم ابزار با ainvoke خطای KeyError: '__pregel_scratchpad' داد، چون تابع interrupt() تنظیمات یک گراف در حال اجرا را می‌خواند {{code libs/langgraph/langgraph/types.py:1030}}. این مورد ToolException نیست، بنابراین به پیام خطای ToolMessage تبدیل نمی‌شود.
  • کنترل‌کننده‌ی اختصاصی. اگر یک fastmcp.Client که elicitation_handler دارد به MCPAdapter داده شود، خودش به سؤال پاسخ می‌دهد. کنترل‌کننده یک بار اجرا شد، ابزار وضعیت موفقیت را برگرداند، و در هر دو نسخه‌ی پروتکل و روی HTTP هیچ وقفه‌ای رخ نداد.
  • سرورهای قدیمی. روی پروتکل نسخه 2025-11-25، سروری که متد ctx.elicit را صدا زد، پاسخی از تطبیق‌دهنده‌ی پیش‌فرض نگرفت. ابزار پیام خطای ToolMessage داد و ایجنت به فراخوانی بعدی مدل پرداخت. متن این خطا در بخش خطاها آمده است.

در دو سناریوی دیگر به جای دریافت پیام خطای ToolMessage، استثنای MCPError از ابزار به بیرون پرتاب شد. ارسال یک fastmcp.Client بدون کنترل‌کننده به تابع as_langchain_tool روی پروتکل 2026-07-28 خطای Elicitation not supported داد. در مقابل، یک کلاینت قدیمی بدون کنترل‌کننده که از طریق ctx.elicit فراخوانی شد، پیام خطای ToolMessage با همان متن را برگرداند. اتصال قدیمی به ابزاری که خروجی InputRequiredResult می‌داد نیز منجر به پرتاب استثنا شد، چون این فرمت نتیجه فقط در پروتکل 2026-07-28 وجود دارد. ما این دو حالت را فقط خارج از ساختار ایجنت آزمایش کردیم. همان‌طور که در سناریوهای کرش کردن سرور دیدیم، هر استثنایی که از جنس ToolException نباشد، کل اجرای ایجنت را متوقف می‌کند.

محتوای ساختاریافته (Structured Content) در زمان بروز خطا. ایشوی شماره 40471 در گیت‌هاب LangChain گزارش می‌دهد که نتیجه‌ی همراه با خطا، محتوای ساختاریافته‌ی (structuredContent) خود را از دست می‌دهد {{issue langchain#40471}}. ابزار سرور ما وضعیت is_error را به همراه متن quota exceeded, retry in 30 s و یک بار داده‌ی (payload) ساختاریافته فرستاد. نتیجه‌ی خام fastmcp هر دو را حفظ کرد، اما پیام ToolMessage در تطبیق‌دهنده فقط متن را نگه داشت:

یک نتیجه خطا، از طریق تطبیق‌دهنده و از طریق fastmcp capture/lab/summary/mcp-edges-mac.json
      {
       "artifact": null,
       "status": "error",
       "step": "direct",
       "text": [
        "quota exceeded, retry in 30 s"
       ],
       "type": "ToolMessage"
      },
      {
       "is_error": true,
       "step": "raw-fastmcp",
       "structured_content": {
        "code": 429,
        "retry_after": 30
       },

رویداد اول ToolMessage است، و رویداد دوم نتیجه خام fastmcp.Client.call_tool است.

علت این مسئله در تابع _convert_call_tool_result است؛ جایی که در صورت خطا بودن خروجی، پیش از ساخت دست‌سازه استثنا پرتاب می‌شود {{code libs/langchain_v1/langchain/mcp/tools.py:168-179}}. سپس کنترل‌کننده‌ی خطا فقط بلوک‌های متنی محتوا را برمی‌گرداند {{code libs/langchain_v1/langchain/mcp/tools.py:104-117}}. همین نتیجه بدون فلگ is_error، دست‌سازه‌ی خود را حفظ کرد. این داده در هر دو نسخه‌ی پروتکل و روی HTTP به همین شکل از بین رفت. بنابراین، اگر سروری فیلد retry_after را فقط در محتوای ساختاریافته‌ی خود بگذارد، کد شما چیزی برای خواندن نخواهد داشت. از سرور بخواهید این مقدار را درون متن پیام هم تکرار کند.

گزارش پیشرفت (Progress). یک ابزار در سرور سه بار روند پیشرفت خود را گزارش داد. در تطبیق‌دهنده‌ی پیش‌فرض، هیچ اطلاعاتی از پیشرفت به دست فراخواننده نرسید. داخل ایجنت، حالت استریم با پارامتر stream_mode="custom" هم هیچ تکه‌ای (chunk) تولید نکرد؛ در نتیجه گزارش پیشرفت تبدیل به رویداد استریم نمی‌شود. اما ارسال شیء fastmcp.Client(target, progress_handler=...) به تطبیق‌دهنده باعث شد هر 3 گزارش پیشرفت دریافت شوند؛ چه در حالت درون‌فرایندی، چه روی HTTP و چه درون ایجنت. دریافت گزارش پیشرفت نیز درست مثل تنظیم تایم‌اوت، نیازمند ساخت دستی کلاینت توسط شما است.

در این نسخه به پروتکل OAuth، استخراج ورودی با مود URL، یا چند درخواست ورودی در یک نوبت پرداخته نشد. فهرست این موارد در بخش 8.8 آمده است.

منابع: capture/s_integrations.py, capture/out/40-mcp.txt; capture/lab/summary/mcp-mac.json, capture/lab/T12-mcp-mac/01-langchain-mcp.jsonl, capture/lab/T12-mcp-mac/02-langchain-mcp-adapters-0.3.2.jsonl, capture/lab/T12-mcp-mac/03-adapters-launch-count.txt, capture/lab/T12-mcp-mac/00-venv-adapters-freeze.txt; capture/lab/summary/mcp-edges-mac.json, capture/lab/T20-mcp-edges-mac/01-mcp-edges.jsonl, capture/lab/T20-mcp-edges-mac/t20_mcp.py, capture/lab/T20-mcp-edges-mac/t20_server.py; libs/langchain_v1/langchain/mcp/adapter.py, libs/langchain_v1/langchain/mcp/elicitation.py, libs/langchain_v1/langchain/mcp/tools.py, and libs/langchain_v1/pyproject.toml at langchain==1.5.0; libs/langgraph/langgraph/types.py at langgraph 1.2.22; issue langchain#40471; pyproject.toml of langchain-mcp-adapters 0.3.2 (cc0f2843); docs.langchain.com at docs commit 04d4d4a (oss/python/releases/changelog, oss/python/langchain/mcp, oss/python/langchain/mcp/tools, oss/python/migrate/langchain-mcp-adapters).

ترجمه‌ی فارسی MCP with langchain.mcp از راهنمای LangChain 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما