ساخت ایجنت هوش مصنوعی با n8n و MCP روی سرور ابری

ساخت ایجنت هوش مصنوعی با n8n از وقتی پشتیبانی بومی از پروتکل MCP به آن اضافه شد، شکل تازه‌ای گرفته است. MCP یا Model Context Protocol یک استاندارد باز است که مشخص می‌کند یک مدل زبانی چطور ابزارهای بیرونی را کشف کند و صدا بزند؛ و n8n از نسخهٔ ۲.۱۸.۴ هم می‌تواند سرور MCP باشد و هم کلاینت آن.

نکته‌ای که باعث سردرگمی زیادی می‌شود این است که در n8n سه چیز متفاوت با نام MCP وجود دارد و هر کدام کار جداگانه‌ای می‌کنند:

• دسترسی MCP در سطح نمونه — کل نمونهٔ n8n شما به یک ابزار برای دستیارهایی مثل Claude یا Cursor تبدیل می‌شود، تا از داخل همان‌ها گردش‌کار بسازند، اجرا کنند و منتشر کنند.
• گرهٔ MCP Client Tool — به یک ایجنتِ داخل n8n اجازه می‌دهد ابزارهای یک سرور MCP بیرونی را استفاده کند.
• گرهٔ MCP Server Trigger — یک گردش‌کار شما را به سروری تبدیل می‌کند که هر کلاینت MCP می‌تواند از آن ابزار بگیرد.

در این راهنما هر سه را روی یک نمونهٔ خودمیزبان راه می‌اندازیم. فرض این است که n8n را از پیش دارید؛ اگر ندارید، آموزش نصب n8n روی Debian 13 با داکر و Nginx نقطهٔ شروع است و بقیهٔ این مقاله دقیقاً روی همان راه‌اندازی سوار می‌شود.

پیش‌نیازها

• یک نمونهٔ n8n نسخهٔ ۲.۱۸.۴ یا بالاتر. دسترسی MCP در سطح نمونه در نسخه‌های قدیمی‌تر وجود ندارد و روی نسخهٔ رایگان خودمیزبان (Community) هم در دسترس است.
• دامنه با HTTPS فعال. کلاینت‌های MCP روی اتصال رمزنگاری‌نشده کار نمی‌کنند و احراز هویت OAuth هم به HTTPS نیاز دارد.
• دسترسی owner یا admin روی نمونهٔ n8n؛ فعال‌کردن MCP فقط با این نقش‌ها ممکن است.
• یک ارائه‌دهندهٔ مدل. برای ایجنت داخل n8n می‌توانید از کلید API سرویس‌های ابری یا از یک نمونهٔ محلی Ollama استفاده کنید؛ آموزش نصب Ollama روی سرور ابری مسیر محلی را توضیح می‌دهد.

گام ۱: به‌روزرسانی n8n

ابتدا نسخهٔ فعلی را ببینید. اگر n8n را با داکر اجرا کرده‌اید:

docker exec n8n n8n --version

اگر عدد کمتر از 2.18.4 بود، ایمیج را به‌روز کنید:

docker pull docker.n8n.io/n8nio/n8n
docker stop n8n && docker rm n8n
# سپس همان دستور docker run قبلی را با ایمیج تازه دوباره اجرا کنید

چون داده‌ها در والیوم n8n_data هستند، حذف و ساخت دوبارهٔ کانتینر چیزی را از بین نمی‌برد. با این حال پیش از ارتقا، یک اسنپ‌شات از سرور در کنترل پنل ابر سپهر بگیرید؛ برگشتن از یک ارتقای ناموفق به این شکل چند دقیقه طول می‌کشد نه چند ساعت.

گام ۲: تنظیم پراکسی برای اتصال‌های طولانی

پیش از فعال‌کردن MCP، یک تغییر در پیکربندی Nginx لازم است. MCP روی دو حالت انتقال کار می‌کند: SSE و Streamable HTTP. هر دو اتصال‌های طولانی‌مدت هستند که داده را قطره‌قطره می‌فرستند، و Nginx به‌صورت پیش‌فرض پاسخ‌ها را بافر می‌کند — یعنی تا وقتی پاسخ کامل نشود چیزی به کلاینت نمی‌رسد و اتصال عملاً هنگ می‌کند.

بلوک زیر را داخل server مربوط به n8n اضافه کنید:

location /mcp-server/ {
    proxy_pass http://127.0.0.1:5678;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    proxy_http_version 1.1;
    proxy_set_header Connection "";

    # اتصال‌های MCP طولانی و جریانی هستند
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}

سپس پیکربندی را بررسی و اعمال کنید:

nginx -t && systemctl reload nginx

خطِ proxy_buffering off مهم‌ترین سطر این بلوک است. اگر آن را جا بیندازید، کلاینت وصل می‌شود اما هیچ پاسخی نمی‌گیرد و پیغام خطای روشنی هم در کار نیست؛ عیب‌یابی این حالت وقت زیادی می‌گیرد.

گام ۳: فعال‌سازی دسترسی MCP در سطح نمونه

وارد n8n شوید و به مسیر Settings → Instance-level MCP بروید. گزینهٔ Enable MCP access را روشن کنید.

در همین صفحه می‌توانید انتخاب کنید کدام گردش‌کارها در دسترس کلاینت قرار بگیرند. این تنظیم را جدی بگیرید: هر گردش‌کاری که اینجا فعال کنید، از بیرون قابل‌فراخوانی می‌شود. با یک یا دو گردش‌کار آزمایشی شروع کنید و بعد دامنه را باز کنید.

سپس پنجرهٔ Connection details را باز کنید. دو روش احراز هویت دارید:

• OAuth2 — روش پیشنهادی. فقط آدرس نمونه را کپی می‌کنید و جریان ورود در خود کلاینت انجام می‌شود.
• Access Token — n8n در نخستین بازدید یک توکن شخصی متصل به حساب شما تولید می‌کند.

توکن دسترسی را همان لحظه کپی کنید. در بازدیدهای بعدی فقط مقدار مخفی‌شده را می‌بینید و راهی برای دیدن دوبارهٔ آن وجود ندارد؛ باید توکن تازه بسازید. مهم‌تر اینکه این توکن به حساب شما وصل است و هر کسی که آن را داشته باشد با اختیارات شما در نمونه کار می‌کند. آن را در فایل پیکربندی مخزن گیت نگذارید.

آدرس نقطهٔ اتصال همیشه این شکل را دارد:

https://n8n.domain.com/mcp-server/http

اگر روزی خواستید این قابلیت را به‌کلی از نمونه بردارید — مثلاً روی نمونه‌ای که چند کاربر دارد — می‌توانید ماژول را با متغیر محیطی غیرفعال کنید:

N8N_DISABLED_MODULES=mcp

گام ۴: وصل‌کردن کلاینت

حالا n8n را به دستیار خودتان معرفی می‌کنیم. برای Claude Code یک دستور کافی است:

claude mcp add --transport http n8n-mcp https://n8n.domain.com/mcp-server/http

این حالت از OAuth استفاده می‌کند و در نخستین اتصال، مرورگر برای ورود باز می‌شود. اگر ترجیح می‌دهید از توکن دسترسی استفاده کنید:

claude mcp add --transport http n8n-mcp https://n8n.domain.com/mcp-server/http \
  --header "Authorization: Bearer YOUR_N8N_MCP_TOKEN"

همین پیکربندی را می‌توانید مستقیم در فایل claude.json هم بنویسید:

{
  "mcpServers": {
    "n8n-mcp": {
      "type": "http",
      "url": "https://n8n.domain.com/mcp-server/http"
    }
  }
}

برای Claude Desktop با OAuth، از مسیر Settings → Connectors یک کانکتور سفارشی با آدرس پایهٔ n8n اضافه کنید. اگر از توکن استفاده می‌کنید، در claude_desktop_config.json بنویسید:

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "npx",
      "args": ["-y", "supergateway", "--streamableHttp",
        "https://n8n.domain.com/mcp-server/http",
        "--header", "Authorization:Bearer YOUR_N8N_MCP_TOKEN"]
    }
  }
}

پس از افزودن کانکتور، کلاینت را دوباره راه‌اندازی کنید. حالا می‌توانید در گفت‌وگو بخواهید یک گردش‌کار ساخته شود — مثلاً «هر روز ساعت ۸ صبح فید RSS فلان سایت را بخوان و عنوان‌های جدید را به تلگرام بفرست» — و نتیجه مستقیماً به‌صورت یک گردش‌کار در نمونهٔ شما ساخته می‌شود. دیگر خبری از کپی‌کردن JSON بین پنجره‌ها نیست.

بهترین کار این است که خروجی را همیشه پیش از فعال‌کردن، در رابط n8n باز کنید و گره‌به‌گره مرور کنید. مدل در ساختن اسکلت گردش‌کار خوب عمل می‌کند، اما در انتخاب اعتبارنامه و جزئیات فیلترها هنوز باید بازبینی شود.

گام ۵: ساخت ایجنت داخل n8n

تا اینجا n8n ابزارِ دستیار بیرونی بود. حالا برعکسش می‌کنیم و ایجنتی می‌سازیم که خودش داخل n8n زندگی می‌کند.

یک گردش‌کار تازه بسازید و این گره‌ها را کنار هم بگذارید:

۱. یک تریگر — برای شروع Chat Trigger ساده‌ترین گزینه است چون یک رابط گفت‌وگو هم به شما می‌دهد.

۲. گرهٔ AI Agent به‌عنوان مغز جریان.

۳. یک Chat Model به‌عنوان زیرگرهٔ مدل. اگر Ollama را روی همان سرور دارید، آدرس آن را http://127.0.0.1:11434 بگذارید و اگر n8n داخل داکر است و Ollama روی خود میزبان، آدرس باید http://host.docker.internal:11434 باشد؛ 127.0.0.1 از داخل کانتینر به خود کانتینر اشاره می‌کند نه به سرور.

۴. یک Memory برای اینکه ایجنت بین پیام‌ها زمینه را نگه دارد.

تا اینجا ایجنتی دارید که حرف می‌زند اما کاری نمی‌کند. کار در گام بعد اضافه می‌شود.

گام ۶: دادن ابزار به ایجنت با MCP Client Tool

زیر گرهٔ AI Agent، یک زیرگره از نوع MCP Client Tool اضافه کنید. این گره ایجنت شما را به یک سرور MCP بیرونی وصل می‌کند و ابزارهای آن را در اختیارش می‌گذارد.

سه فیلد مهم دارد:

• SSE Endpoint — آدرس سرور MCP مقصد.
• Authentication — یکی از Bearer، هدر عمومی، چند هدر هم‌زمان، OAuth2 یا بدون احراز هویت. اگر سرور مقصد هم کلید API می‌خواهد و هم نام کاربری، حالت چندهدری همان چیزی است که لازم دارید.
• Tools to Include — سه حالت دارد: All که همهٔ ابزارها را باز می‌گذارد، Selected که فقط موارد انتخابی، و All Except که همه‌چیز جز مواردی که کنار می‌گذارید.

روی All نمانید. هر ابزاری که در اختیار مدل بگذارید هم توکن مصرف می‌کند (توضیح ابزارها در هر فراخوانی به مدل فرستاده می‌شود) و هم یک احتمال خطاست. با Selected و دو سه ابزاری که واقعاً لازم دارید شروع کنید؛ کیفیت تصمیم‌گیری ایجنت هم بهتر می‌شود چون فهرست انتخاب‌هایش کوتاه‌تر است.

گام ۷: انتشار گردش‌کار خودتان به‌عنوان سرور MCP

طرف سوم ماجرا این است که گردش‌کارهای خودتان را به ابزار تبدیل کنید تا هر کلاینت MCP از آن‌ها استفاده کند. گرهٔ MCP Server Trigger دقیقاً همین کار را می‌کند.

یک گردش‌کار تازه بسازید و این گره را به‌عنوان تریگر بگذارید. چند نکتهٔ پیکربندی:

• فیلد Path به‌صورت خودکار با یک رشتهٔ تصادفی پر می‌شود تا با گره‌های مشابه در گردش‌کارهای دیگر تداخل نکند. می‌توانید مسیر دلخواه بگذارید، ولی مقدار تصادفی امن‌تر است.
• برای Authentication یکی از Bearer auth یا Header auth را انتخاب کنید. حالت بدون احراز هویت یعنی هر کسی که مسیر را حدس بزند می‌تواند گردش‌کار شما را اجرا کند.
• گره دو آدرس می‌دهد: Test که فقط هنگام اجرای دستی در ویرایشگر فعال است، و Production که پس از فعال‌کردن گردش‌کار کار می‌کند. اگر کلاینت وصل می‌شود ولی چیزی برنمی‌گردد، اولین چیزی که باید بررسی کنید همین است که آدرس Test را در حالت پروداکشن استفاده نکرده باشید.

زیر این تریگر، هر گرهٔ ابزاری که وصل کنید به‌عنوان یک tool در اختیار کلاینت قرار می‌گیرد. توضیح هر ابزار را با دقت بنویسید؛ مدل فقط بر اساس همین توضیح تصمیم می‌گیرد که کدام ابزار را صدا بزند.

این گره از SSE و Streamable HTTP پشتیبانی می‌کند اما از انتقال stdio پشتیبانی نمی‌کند. اگر n8n را در حالت صف (queue mode) با چند رپلیکای webhook اجرا می‌کنید، باید تمام درخواست‌های /mcp* را به یک رپلیکای مشخص مسیریابی کنید؛ این اتصال‌ها پایدارند و اگر بین رپلیکاها پخش شوند، وسط کار قطع می‌شوند.

نگهداری و امنیت

نقطهٔ اتصال /mcp-server/http محدودیت نرخ درخواست دارد که بر اساس آی‌پی و در بازهٔ پنج‌دقیقه‌ای اعمال می‌شود و با متغیرهای محیطی قابل تنظیم است. اگر کلاینتی مدام خطای محدودیت نرخ می‌گیرد، پیش از بالا بردن سقف بررسی کنید که در حلقه گیر نکرده باشد.

از نظر بک‌آپ چیزی نسبت به قبل عوض نمی‌شود: تمام گردش‌کارها، اعتبارنامه‌ها و تنظیمات MCP در همان والیوم n8n_data می‌مانند. برای بک‌آپ منظم و رمزنگاری‌شدهٔ این والیوم، بک‌آپ خودکار سرور با Restic روش پایداری پیشنهاد می‌دهد.

جمع‌بندی

ساخت ایجنت هوش مصنوعی با n8n و MCP در عمل یعنی سه کار جدا که هر کدام جای خودش را دارد: نمونهٔ n8n را به دستیار بیرونی وصل کنید تا گردش‌کارها را با زبان طبیعی بسازد، با MCP Client Tool ابزارهای بیرونی را به ایجنت داخلی بدهید، و با MCP Server Trigger گردش‌کارهای خودتان را به ابزار تبدیل کنید.

سه تصمیمی که بیشترین تفاوت را می‌سازند: خاموش‌کردن بافرینگ Nginx روی مسیر /mcp-server/ که بدون آن هیچ‌چیز کار نمی‌کند، انتخاب OAuth به‌جای توکن ثابت هرجا که ممکن است، و محدودکردن فهرست ابزارها و گردش‌کارهای در دسترس به‌جای باز گذاشتن همه‌چیز.

اگر می‌خواهید مدل را هم روی همان زیرساخت نگه دارید و چیزی از سرور بیرون نرود، به منابع بیشتری نیاز دارید؛ از صفحهٔ خرید سرور ابری می‌توانید نمونه‌ای متناسب با اندازهٔ مدل انتخاب کنید و بعداً منابع را ارتقا دهید.