اتصال Claude Code به ابزارها از طریق MCP

Claude Code می‌تواند از طریق Model Context Protocol (MCP) — یک استانداردِ متن‌بازِ یکپارچه‌سازیِ AI با ابزارها — به صدها ابزار و منبعِ داده‌ی بیرونی وصل شود. سرورهای MCP به Claude Code دسترسی به ابزارها، پایگاه‌داده‌ها و APIهای تو را می‌دهند.

هر وقت دیدی داری داده‌ای را از ابزارِ دیگری — مثل issue tracker یا داشبوردِ مانیتورینگ — کپی می‌کنی توی چت، یک سرور وصل کن. وقتی وصل شد، Claude می‌تواند به‌جای کار کردن روی چیزی که می‌چسبانی، مستقیماً آن سیستم را بخواند و رویش اقدام کند.

اگر داری اولین سرورت را وصل می‌کنی، با شروعِ سریعِ MCP آغاز کن که گام‌به‌گام راهنمایی‌ات می‌کند. این صفحه مرجعِ کامل است.

با MCP چه کارهایی می‌توانی بکنی

با سرورهای MCPِ وصل‌شده، می‌توانی از Claude Code بخواهی:

پیاده‌سازیِ قابلیت‌ها از issue trackerها: «قابلیتی که در issueِ JIRA با شماره‌ی ENG-4521 توضیح داده شده را اضافه کن و روی GitHub یک PR بساز.»
تحلیلِ داده‌های مانیتورینگ: «Sentry و Statsig را بررسی کن تا میزانِ استفاده از قابلیتِ توضیح‌داده‌شده در ENG-4521 را ببینی.»
کوئری از پایگاه‌داده: «بر اساسِ پایگاه‌داده‌ی PostgreSQLمان، ایمیلِ ۱۰ کاربرِ تصادفی که از قابلیتِ ENG-4521 استفاده کرده‌اند را پیدا کن.»
یکپارچه‌سازیِ طراحی‌ها: «قالبِ استانداردِ ایمیلِ‌مان را بر اساسِ طراحی‌های جدیدِ Figma که در Slack پست شده، به‌روز کن»
خودکارسازیِ ورک‌فلوها: «برای این ۱۰ کاربر draftهای Gmail بساز که دعوتشان کنی به یک جلسه‌ی بازخورد درباره‌ی قابلیتِ جدید.»
واکنش به رویدادهای بیرونی: یک سرور MCP می‌تواند به‌عنوان یک کانال هم عمل کند که پیام‌ها را به نشستِ تو push می‌کند، تا Claude در غیابِ تو به پیام‌های Telegram، چت‌های Discord یا رویدادهای webhook واکنش نشان دهد.

پیدا کردن و ساختنِ سرورهای MCP

کانکتورهای بازبینی‌شده را در دایرکتوریِ Anthropic مرور کن. کانکتورهای دایرکتوری از همان زیرساختِ MCPِ Claude Code استفاده می‌کنند، پس می‌توانی هر سرورِ راه‌دورِ فهرست‌شده آنجا را با claude mcp add اضافه کنی.

برای ساختنِ سرورِ خودت، راهنمای سرور MCP را برای مبانیِ پروتکل و مستنداتِ ساختِ کانکتورِ Claude را برای احراز هویت، تست و ارسال به دایرکتوری ببین.

همچنین می‌توانی با پلاگینِ رسمیِ mcp-server-dev از Claude بخواهی که یک سرور برایت اسکفولد کند.

نصبِ پلاگین

در یک نشستِ Claude Code، اجرا کن:

/plugin install mcp-server-dev@claude-plugins-official

اگر Claude Code گزارش داد که marketplace پیدا نشد، اول /plugin marketplace add anthropics/claude-plugins-official را اجرا کن، بعد دوباره نصب را امتحان کن. وقتی نصب شد، /reload-plugins را اجرا کن تا در نشستِ جاری فعال شود.

اجرای اسکیلِ ساخت

/mcp-server-dev:build-mcp-server

Claude درباره‌ی کاربردِ تو می‌پرسد و یک سرورِ راه‌دورِ HTTP یا سرورِ محلیِ stdio را اسکفولد می‌کند.

نصبِ سرورهای MCP

سرورهای MCP بسته به نیازت به چند روش قابلِ پیکربندی‌اند:

گزینه‌ی ۱: افزودنِ یک سرورِ راه‌دورِ HTTP

سرورهای HTTP گزینه‌ی توصیه‌شده برای اتصال به سرورهای راه‌دورِ MCP هستند. این پُرپشتیبانی‌ترین transport برای سرویس‌های ابری است.

# Basic syntax
claude mcp add --transport http <name> <url>

# Real example: Connect to Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Example with Bearer token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

وقتی سرورهای MCP را از طریقِ JSON در .mcp.json، ~/.claude.json یا claude mcp add-json پیکربندی می‌کنی، فیلدِ type مقدارِ streamable-http را به‌عنوانِ نامِ مستعارِ http می‌پذیرد. مشخصاتِ MCP برای این transport از نامِ streamable-http استفاده می‌کند، پس پیکربندی‌های کپی‌شده از مستنداتِ سرور بدونِ تغییر کار می‌کنند.

گزینه‌ی ۲: افزودنِ یک سرورِ راه‌دورِ SSE

# Basic syntax
claude mcp add --transport sse <name> <url>

# Real example: Connect to Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Example with authentication header
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

گزینه‌ی ۳: افزودنِ یک سرورِ محلیِ stdio

سرورهای stdio به‌صورتِ پروسه‌های محلی روی ماشینِ تو اجرا می‌شوند. برای ابزارهایی که به دسترسیِ مستقیمِ سیستمی یا اسکریپت‌های سفارشی نیاز دارند ایده‌آل‌اند.

Claude Code متغیرِ CLAUDE_PROJECT_DIR را در محیطِ سرورِ spawn‌شده برابرِ ریشه‌ی پروژه قرار می‌دهد، تا سرورِ تو بتواند مسیرهای نسبت‌به‌پروژه را بدونِ وابستگی به دایرکتوریِ کاری حل کند. این همان دایرکتوری‌ای است که hookها در متغیرِ CLAUDE_PROJECT_DIRشان دریافت می‌کنند. از داخلِ پروسه‌ی سرورت آن را بخوان، مثلاً process.env.CLAUDE_PROJECT_DIR در Node یا os.environ["CLAUDE_PROJECT_DIR"] در Python. سرورت همچنین می‌تواند درخواستِ MCPِ roots/list را صدا بزند، که دایرکتوری‌ای را که Claude Code از آن راه‌اندازی شده برمی‌گرداند.

این متغیر در محیطِ سرور تنظیم می‌شود، نه در محیطِ خودِ Claude Code، پس ارجاع به آن از طریقِ بسطِ ${VAR} در command یا argsِ یک .mcp.jsonِ پروژه‌ای یا کاربری نیازمندِ یک مقدارِ پیش‌فرض مثلِ ${CLAUDE_PROJECT_DIR:-.} است. پیکربندی‌های MCPِ فراهم‌شده توسطِ پلاگین، ${CLAUDE_PROJECT_DIR} را مستقیماً جایگزین می‌کنند و به پیش‌فرض نیاز ندارند.

# Basic syntax
claude mcp add [options] <name> -- <command> [args...]

# Real example: Add Airtable server
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

مهم: آرگومان‌های سرور را با -- جدا کن

برای سرورهای stdio، -- (دو خط‌تیره) گزینه‌های خودِ Claude — مثلِ --transport، --env و --scope — را از دستور و آرگومان‌هایی که سرور را اجرا می‌کنند جدا می‌کند. هر چیزی بعد از -- دست‌نخورده به سرور پاس داده می‌شود.

برای مثال:

claude mcp add --transport stdio myserver -- npx server ← npx server را اجرا می‌کند
claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080 ← python server.py --port 8080 را با KEY=value در محیط اجرا می‌کند

بدونِ --، Claude Code تلاش می‌کرد پرچم‌های سرور — مثلِ --port در بالا — را به‌عنوانِ گزینه‌های خودش parse کند.

--env چند جفتِ KEY=value را می‌پذیرد. اگر نامِ سرور مستقیماً بعد از --env بیاید، CLI آن نام را به‌عنوانِ یک جفتِ دیگر می‌خواند و ردش می‌کند، پس دستِ‌کم یک گزینه‌ی دیگر بینِ --env و نامِ سرور بگذار، مثلِ مثال‌های بالا.

گزینه‌ی ۴: افزودنِ یک سرورِ راه‌دورِ WebSocket

سرورهای WebSocket یک اتصالِ دوطرفه‌ی پایدار نگه می‌دارند، که مناسبِ سرورهای راه‌دورِ MCP است که بدونِ درخواست رویدادها را به Claude push می‌کنند. وقتی سرورت فقط به درخواست‌ها پاسخ می‌دهد، به‌جایش از HTTP استفاده کن، چون HTTP از OAuth و پرچمِ claude mcp add --transport پشتیبانی می‌کند، حال‌آنکه WebSocket از هیچ‌کدام پشتیبانی نمی‌کند.

سرورهای WebSocket را در .mcp.json یا با claude mcp add-json پیکربندی کن:

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

ورودیِ type: "ws" همان فیلدهای url، headers، headersHelper، timeout و alwaysLoadِ http را می‌پذیرد. احراز هویت فقط با header انجام می‌شود، پس یا یک توکنِ ثابت در headers پاس بده یا هنگامِ اتصال یکی با headersHelper بساز. پرچمِ claude mcp add --transport مقدارِ ws را نمی‌پذیرد.

مدیریتِ سرورهایت

وقتی پیکربندی شد، می‌توانی سرورهای MCPت را با این دستورها مدیریت کنی:

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get github

# Remove a server
claude mcp remove github

# (within Claude Code) Check server status
/mcp

سرورهای پروژه‌ای از .mcp.json که منتظرِ تأییدِ تو هستند، در claude mcp list به‌صورتِ ⏸ Pending approval نشان داده می‌شوند. claude را به‌صورتِ تعاملی اجرا کن تا بازبینی و تأییدشان کنی. claude mcp get <name> سرورهای در انتظار را به‌صورتِ ⏸ Pending approval و سرورهای ردشده را به‌صورتِ ✗ Rejected نشان می‌دهد.

پنلِ /mcp تعدادِ ابزارها را کنارِ هر سرورِ متصل نشان می‌دهد و سرورهایی را که قابلیتِ ابزار را تبلیغ می‌کنند ولی هیچ ابزاری ارائه نمی‌دهند، علامت می‌زند.

اگر درخواستِ تو به ابزارهایی از سروری نیاز داشته باشد که هنوز در پس‌زمینه در حالِ اتصال است، Claude پیش از ادامه منتظرِ آن سرور می‌ماند. با جست‌وجوی ابزار فعال — که حالتِ پیش‌فرض است — این انتظار داخلِ فراخوانِ ToolSearch رخ می‌دهد. در پیکربندی‌های بدونِ جست‌وجوی ابزار — مثلِ Vertex AI، یک ANTHROPIC_BASE_URLِ سفارشی، یا ENABLE_TOOL_SEARCH=false — به‌جایش Claude از ابزارِ WaitForMcpServers استفاده می‌کند.

نامِ سرورِ workspace برای استفاده‌ی داخلی رزرو شده است. اگر پیکربندیِ تو سروری با آن نام تعریف کند، Claude Code هنگامِ بارگذاری از آن می‌گذرد و هشداری نشان می‌دهد که بخواهد تغییرِ نامش دهی.

به‌روزرسانیِ پویای ابزارها

Claude Code از اعلان‌های list_changedِ MCP پشتیبانی می‌کند، که به سرورهای MCP اجازه می‌دهد ابزارها، پرامپت‌ها و منابعِ در دسترسِ خود را به‌صورتِ پویا به‌روز کنند، بدونِ اینکه نیاز باشد قطع‌ووصل کنی. وقتی یک سرور MCP اعلانِ list_changed بفرستد، Claude Code به‌صورتِ خودکار قابلیت‌های در دسترسِ آن سرور را تازه می‌کند.

اتصالِ مجددِ خودکار

اگر یک سرورِ HTTP یا SSE در میانه‌ی نشست قطع شود، Claude Code به‌صورتِ خودکار با backoffِ نمایی دوباره وصل می‌شود: تا پنج تلاش، با شروع از یک ثانیه تأخیر که هر بار دو برابر می‌شود. سرور تا وقتی اتصالِ مجدد در جریان است در /mcp به‌صورتِ pending نشان داده می‌شود. بعد از پنج تلاشِ ناموفق، سرور به‌عنوانِ failed علامت می‌خورد و می‌توانی از /mcp دستی دوباره تلاش کنی. سرورهای stdio پروسه‌های محلی‌اند و به‌صورتِ خودکار دوباره وصل نمی‌شوند.

همین backoff وقتی هم اعمال می‌شود که یک سرورِ HTTP یا SSE در آغازِ کار اتصالِ اولیه‌اش شکست بخورد. از نسخه‌ی v2.1.121، Claude Code اتصالِ اولیه را در خطاهای گذرا مثلِ پاسخِ 5xx، connection refused یا timeout تا سه بار تلاش می‌کند، بعد اگر همچنان نتواند وصل شود، سرور را failed علامت می‌زند. خطاهای احراز هویت و not-found دوباره تلاش نمی‌شوند چون برای حل‌شدن به تغییرِ پیکربندی نیاز دارند.

push کردنِ پیام‌ها با کانال‌ها

یک سرور MCP می‌تواند پیام‌ها را مستقیماً به نشستِ تو push کند تا Claude به رویدادهای بیرونی مثلِ نتایجِ CI، هشدارهای مانیتورینگ یا پیام‌های چت واکنش نشان دهد. برای فعال‌سازیِ این، سرورت قابلیتِ claude/channel را اعلام می‌کند و تو با پرچمِ --channels هنگامِ راه‌اندازی واردش می‌کنی. برای استفاده از یک کانالِ رسماً پشتیبانی‌شده کانال‌ها را ببین، یا برای ساختنِ کانالِ خودت مرجعِ کانال‌ها را.

نکته‌ها:

از پرچمِ --scope برای تعیینِ محلِ ذخیره‌ی پیکربندی استفاده کن:
- local (پیش‌فرض): فقط برای تو و در پروژه‌ی جاری در دسترس است (در نسخه‌های قدیمی‌تر project نامیده می‌شد)
- project: از طریقِ فایلِ .mcp.json با همه‌ی اعضای پروژه به اشتراک گذاشته می‌شود
- user: در همه‌ی پروژه‌هایت برای تو در دسترس است (در نسخه‌های قدیمی‌تر global نامیده می‌شد)
متغیرهای محیطی را با پرچم‌های --env تنظیم کن (مثلاً --env KEY=value)
timeoutِ راه‌اندازیِ سرورِ MCP را با متغیرِ محیطیِ MCP_TIMEOUT پیکربندی کن (مثلاً MCP_TIMEOUT=10000 claude یک timeoutِ ۱۰ ثانیه‌ای تعیین می‌کند)
یک timeoutِ اجرای ابزار به‌ازای هر سرور را با افزودنِ فیلدِ timeout بر حسبِ میلی‌ثانیه به ورودیِ آن سرور در .mcp.json تنظیم کن، مثلاً "timeout": 600000 برای ده دقیقه. این برای همان سرور، متغیرِ محیطیِ MCP_TOOL_TIMEOUT را override می‌کند
وقتی خروجیِ ابزارِ MCP از ۱۰٬۰۰۰ توکن بیشتر شود، Claude Code هشدار نشان می‌دهد. برای بالا بردنِ این حد، متغیرِ محیطیِ MAX_MCP_OUTPUT_TOKENS را تنظیم کن (مثلاً MAX_MCP_OUTPUT_TOKENS=50000)
برای احراز هویت با سرورهای راه‌دوری که OAuth 2.0 می‌خواهند از /mcp استفاده کن

فیلدِ timeoutِ هر سرور یک سقفِ سختِ زمانِ واقعی به‌ازای هر فراخوانِ ابزار است، و اعلان‌های پیشرفت از سوی سرور آن را تمدید نمی‌کنند. مقادیرِ کمتر از 1000 نادیده گرفته می‌شوند و به MCP_TOOL_TIMEOUT می‌رسند، یا اگر آن متغیر تنظیم نشده باشد، به پیش‌فرضش که حدودِ ۲۸ ساعت است. {/* min-version: 2.1.162 */}پیش از v2.1.162، مقادیرِ کمتر از 1000 به‌جایش به یک ثانیه کف می‌خوردند. برای سرورهای HTTP و SSE، بودجه‌ی اولین‌بایتِ fetch به‌ازای هر درخواست یک کفِ ۶۰ ثانیه‌ای دارد.

سرورهای MCPِ فراهم‌شده توسطِ پلاگین

پلاگین‌ها می‌توانند سرورهای MCP را در خود بسته‌بندی کنند، و وقتی پلاگین فعال شد به‌صورتِ خودکار ابزارها و یکپارچه‌سازی‌ها را فراهم کنند. سرورهای MCPِ پلاگین دقیقاً مثلِ سرورهای پیکربندی‌شده توسطِ کاربر کار می‌کنند.

سرورهای MCPِ پلاگین چطور کار می‌کنند:

پلاگین‌ها سرورهای MCP را در .mcp.jsonِ ریشه‌ی پلاگین یا به‌صورتِ inline در plugin.json تعریف می‌کنند
وقتی یک پلاگین فعال می‌شود، سرورهای MCPش به‌صورتِ خودکار شروع می‌شوند
ابزارهای MCPِ پلاگین در کنارِ ابزارهای MCPِ پیکربندی‌شده‌ی دستی ظاهر می‌شوند
سرورهای پلاگین از طریقِ نصبِ پلاگین مدیریت می‌شوند (نه دستورهای /mcp)

نمونه‌ی پیکربندیِ MCPِ پلاگین:

در .mcp.jsonِ ریشه‌ی پلاگین:

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

یا به‌صورتِ inline در plugin.json:

{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

قابلیت‌های MCPِ پلاگین:

چرخه‌ی حیاتِ خودکار: هنگامِ راه‌اندازیِ نشست، سرورهای پلاگین‌های فعال به‌صورتِ خودکار وصل می‌شوند. اگر در طولِ یک نشست پلاگینی را فعال یا غیرفعال کنی، /reload-plugins را اجرا کن تا سرورهای MCPش وصل یا قطع شوند
متغیرهای محیطی: از ${CLAUDE_PLUGIN_ROOT} برای فایل‌های بسته‌بندی‌شده‌ی پلاگین، از ${CLAUDE_PLUGIN_DATA} برای وضعیتِ ماندگار که از به‌روزرسانیِ پلاگین جان سالم به‌در می‌برد، و از ${CLAUDE_PROJECT_DIR} برای ریشه‌ی پایدارِ پروژه استفاده کن
دسترسی به محیطِ کاربر: دسترسی به همان متغیرهای محیطیِ سرورهای پیکربندی‌شده‌ی دستی
چند نوع transport: پشتیبانی از transportهای stdio، SSE، HTTP و WebSocket (پشتیبانی از transport ممکن است بسته به سرور فرق کند)

دیدنِ سرورهای MCPِ پلاگین:

# Within Claude Code, see all MCP servers including plugin ones
/mcp

سرورهای پلاگین در فهرست با نشانه‌هایی ظاهر می‌شوند که می‌گویند از پلاگین می‌آیند.

نام‌های ابزارِ MCPِ پلاگین:

ابزارهای یک سرورِ MCPِ بسته‌بندی‌شده در پلاگین، هم نامِ پلاگین و هم کلیدِ سرور را در نامِ قابلِ‌فراخوانی‌شان دارند. شکلِ کامل mcp__plugin_<plugin-name>_<server-name>__<tool-name> است، که در آن هر کاراکترِ خارج از A-Z، a-z، 0-9، _ و - با _ جایگزین می‌شود. برای سرورِ database-toolsِ بسته‌بندی‌شده در پلاگینی به نامِ my-plugin، یک ابزارِ query این‌طور قابلِ فراخوانی است:

mcp__plugin_my-plugin_database-tools__query

هنگامِ ارجاع به ابزار در قواعدِ دسترسی، فهرستِ allowed-toolsِ یک اسکیل، یا فیلدِ toolsِ یک ساب‌ایجنت، از این نامِ کامل استفاده کن.

مزایای سرورهای MCPِ پلاگین:

توزیعِ بسته‌بندی‌شده: ابزارها و سرورها با هم بسته می‌شوند
راه‌اندازیِ خودکار: نیازی به پیکربندیِ دستیِ MCP نیست
یکدستیِ تیم: وقتی پلاگین نصب شد، همه همان ابزارها را می‌گیرند

برای جزئیاتِ بسته‌بندیِ سرورهای MCP با پلاگین‌ها، مرجعِ کامپوننت‌های پلاگین را ببین.

scopeهای نصبِ MCP

سرورهای MCP در سه scope قابلِ پیکربندی‌اند. scopeای که انتخاب می‌کنی تعیین می‌کند سرور در کدام پروژه‌ها بارگذاری شود و آیا پیکربندی با تیمت به اشتراک گذاشته شود. ادمین‌ها هم می‌توانند سرورها را در سطحِ enterprise از طریقِ پیکربندیِ مدیریت‌شده مستقر کنند.

Scope	بارگذاری در	اشتراک با تیم	ذخیره در
Local	فقط پروژه‌ی جاری	خیر	`~/.claude.json`
Project	فقط پروژه‌ی جاری	بله، از طریقِ version control	`.mcp.json` در ریشه‌ی پروژه
User	همه‌ی پروژه‌هایت	خیر	`~/.claude.json`

scopeِ Local

scopeِ local پیش‌فرض است. یک سرورِ local-scoped فقط در پروژه‌ای که آن را اضافه کرده‌ای بارگذاری می‌شود و خصوصیِ تو می‌ماند. Claude Code آن را در ~/.claude.json زیرِ مسیرِ همان پروژه ذخیره می‌کند، پس همان سرور در پروژه‌های دیگرت ظاهر نمی‌شود. از scopeِ local برای سرورهای توسعه‌ی شخصی، پیکربندی‌های آزمایشی، یا سرورهایی با اعتباری که نمی‌خواهی در version control باشد استفاده کن.

# Add a local-scoped server (default)
claude mcp add --transport http stripe https://mcp.stripe.com

# Explicitly specify local scope
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

این دستور سرور را در ورودیِ پروژه‌ی جاری‌ات داخلِ ~/.claude.json می‌نویسد. مثالِ زیر نتیجه را وقتی نشان می‌دهد که آن را از /path/to/your/project اجرا می‌کنی:

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

scopeِ Project

سرورهای project-scoped با ذخیره‌ی پیکربندی‌ها در فایلِ .mcp.jsonِ ریشه‌ی پروژه، همکاریِ تیمی را ممکن می‌کنند. این فایل طوری طراحی شده که در version control checkin شود، و مطمئن شود همه‌ی اعضای تیم به همان ابزارها و سرویس‌های MCP دسترسی دارند. وقتی یک سرورِ project-scoped اضافه می‌کنی، Claude Code به‌صورتِ خودکار این فایل را با ساختارِ پیکربندیِ مناسب می‌سازد یا به‌روز می‌کند.

# Add a project-scoped server
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

فایلِ .mcp.jsonِ حاصل از یک قالبِ استاندارد پیروی می‌کند:

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

به دلایلِ امنیتی، Claude Code پیش از استفاده از سرورهای project-scopedِ .mcp.json برای تأیید می‌پرسد. اگر لازم شد این انتخاب‌های تأیید را ریست کنی، از دستورِ claude mcp reset-project-choices استفاده کن.

scopeِ User

سرورهای user-scoped در ~/.claude.json ذخیره می‌شوند و دسترسیِ میان‌پروژه‌ای فراهم می‌کنند، یعنی در همه‌ی پروژه‌های روی ماشینت در دسترس‌اند ولی خصوصیِ حسابِ کاربری‌ات می‌مانند. این scope برای سرورهای ابزاریِ شخصی، ابزارهای توسعه، یا سرویس‌هایی که مرتب در پروژه‌های مختلف استفاده می‌کنی خوب کار می‌کند.

# Add a user server
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

سلسله‌مراتب و تقدمِ scopeها

وقتی یک سرور در بیش از یک جا تعریف شده باشد، Claude Code یک بار به آن وصل می‌شود، با استفاده از تعریفِ منبعی که بالاترین تقدم را دارد. تمامِ ورودیِ سرور از آن منبع استفاده می‌شود؛ فیلدها میانِ scopeها merge نمی‌شوند.

سه scope تکراری‌ها را بر اساسِ نام تطبیق می‌دهند. پلاگین‌ها و کانکتورها بر اساسِ endpoint تطبیق می‌خورند، پس آنی که به همان URL یا command یک سرورِ بالاتر اشاره کند، به‌عنوانِ تکراری در نظر گرفته می‌شود.

بسطِ متغیرِ محیطی در `.mcp.json`

Claude Code از بسطِ متغیرِ محیطی در فایل‌های .mcp.json پشتیبانی می‌کند، که به تیم‌ها اجازه می‌دهد پیکربندی‌ها را به اشتراک بگذارند و در عینِ حال برای مسیرهای مخصوصِ هر ماشین و مقادیرِ حساس مثلِ کلیدهای API انعطاف نگه دارند.

نحوِ پشتیبانی‌شده:

${VAR} - به مقدارِ متغیرِ محیطیِ VAR بسط می‌یابد
${VAR:-default} - اگر VAR تنظیم شده باشد به آن بسط می‌یابد، وگرنه از default استفاده می‌کند

محل‌های بسط: متغیرهای محیطی را می‌توان در این‌ها بسط داد:

command - مسیرِ فایلِ اجراییِ سرور
args - آرگومان‌های خطِ فرمان
env - متغیرهای محیطیِ پاس‌شده به سرور
url - برای نوع‌های سرورِ HTTP
headers - برای احراز هویتِ سرورِ HTTP

مثال با بسطِ متغیر:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

اگر یک متغیرِ محیطیِ موردِنیاز تنظیم نشده باشد و مقدارِ پیش‌فرض هم نداشته باشد، Claude Code در parse کردنِ پیکربندی شکست می‌خورد.

مثال‌های عملی

مثال: مانیتورِ خطاها با Sentry

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

با حسابِ Sentryات احراز هویت کن:

/mcp

بعد مشکلاتِ production را دیباگ کن:

What are the most common errors in the last 24 hours?

Show me the stack trace for error ID abc123

Which deployment introduced these new errors?

مثال: اتصال به GitHub برای code review

سرورِ راه‌دورِ MCPِ GitHub با یک personal access tokenِ GitHub که به‌عنوانِ header پاس داده می‌شود احراز هویت می‌کند. برای گرفتنِ یکی، تنظیماتِ توکنِ GitHubات را باز کن، یک fine-grained tokenِ جدید با دسترسی به مخزن‌هایی که می‌خواهی Claude رویشان کار کند بساز، بعد سرور را اضافه کن:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

بعد با GitHub کار کن:

Review PR #456 and suggest improvements

Create a new issue for the bug we just found

Show me all open PRs assigned to me

مثال: کوئری از پایگاه‌داده‌ی PostgreSQLات

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

بعد به‌طور طبیعی از پایگاه‌داده‌ات کوئری بگیر:

What's our total revenue this month?

Show me the schema for the orders table

Find customers who haven't made a purchase in 90 days

احراز هویت با سرورهای راه‌دورِ MCP

بسیاری از سرورهای ابریِ MCP نیاز به احراز هویت دارند. Claude Code برای اتصال‌های امن از OAuth 2.0 پشتیبانی می‌کند.

Claude Code وقتی یک سرورِ راه‌دور با 401 Unauthorized یا 403 Forbidden پاسخ دهد، آن را به‌عنوانِ نیازمندِ احراز هویت علامت می‌زند. هر کدام از این کدهای وضعیت، سرور را در /mcp علامت‌گذاری می‌کند تا بتوانی جریانِ OAuth را کامل کنی. یک سرورِ سفارشی که یک headerِ WWW-Authenticate با اشاره به authorization serverش برمی‌گرداند، همان discoveryِ خودکارِ هر سرورِ راه‌دورِ دیگر را می‌گیرد.

اگر برای سرور headers.Authorization پیکربندی کردی و سرور آن header را رد کرد، Claude Code به‌جای fallback به OAuth، اتصال را به‌عنوانِ failed گزارش می‌کند. بررسی کن که توکن برای endpointِ MCP معتبر است، یا header را بردار تا از جریانِ OAuth استفاده شود.

افزودنِ سروری که نیاز به احراز هویت دارد

برای مثال:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

استفاده از دستورِ /mcp داخلِ Claude Code

در Claude Code، از این دستور استفاده کن:

/mcp

بعد گام‌ها را در مرورگرت دنبال کن تا وارد شوی.

استفاده از یک پورتِ ثابتِ callbackِ OAuth

بعضی سرورهای MCP به یک redirect URIِ مشخص که از پیش ثبت شده نیاز دارند. به‌صورتِ پیش‌فرض، Claude Code یک پورتِ تصادفیِ در دسترس را برای callbackِ OAuth انتخاب می‌کند. از --callback-port استفاده کن تا پورت را ثابت کنی که با یک redirect URIِ از پیش‌ثبت‌شده به شکلِ http://localhost:PORT/callback بخواند.

می‌توانی --callback-port را تنها (با ثبتِ پویای client) یا همراه با --client-id (با اعتبارِ از پیش‌پیکربندی‌شده) استفاده کنی.

# Fixed callback port with dynamic client registration
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

استفاده از اعتبارِ از پیش‌پیکربندی‌شده‌ی OAuth

بعضی سرورهای MCP از راه‌اندازیِ خودکارِ OAuth از طریقِ Dynamic Client Registration پشتیبانی نمی‌کنند. اگر خطایی مثلِ «Incompatible auth server: does not support dynamic client registration» دیدی، سرور به اعتبارِ از پیش‌پیکربندی‌شده نیاز دارد. Claude Code همچنین از سرورهایی پشتیبانی می‌کند که به‌جای Dynamic Client Registration از یک Client ID Metadata Document (CIMD) استفاده می‌کنند، و این‌ها را خودکار discover می‌کند. اگر discoveryِ خودکار شکست خورد، اول یک appِ OAuth از طریقِ پورتالِ توسعه‌دهنده‌ی سرور ثبت کن، بعد هنگامِ افزودنِ سرور اعتبار را فراهم کن.

ثبتِ یک appِ OAuth با سرور

یک app از طریقِ پورتالِ توسعه‌دهنده‌ی سرور بساز و client ID و client secretات را یادداشت کن.

بسیاری از سرورها به یک redirect URI هم نیاز دارند. اگر چنین بود، یک پورت انتخاب کن و یک redirect URI به شکلِ http://localhost:PORT/callback ثبت کن. همان پورت را در گامِ بعد با --callback-port استفاده کن.

افزودنِ سرور با اعتبارت

یکی از روش‌های زیر را انتخاب کن. پورتِ استفاده‌شده برای --callback-port می‌تواند هر پورتِ در دسترسی باشد. فقط باید با redirect URIای که در گامِ قبل ثبت کردی بخواند.

از --client-id برای پاس‌دادنِ client IDِ appت استفاده کن. پرچمِ --client-secret با ورودیِ پنهان برای secret درخواست می‌دهد:

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

شیءِ oauth را در پیکربندیِ JSON بگنجان و --client-secret را به‌عنوانِ یک پرچمِ جدا پاس بده:

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
  --client-secret

از --callback-port بدونِ client ID استفاده کن تا پورت را ثابت کنی و در عینِ حال از ثبتِ پویای client استفاده شود:

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

secret را از طریقِ متغیرِ محیطی تنظیم کن تا از promptِ تعاملی رد شوی:

MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

احراز هویت در Claude Code

در Claude Code، /mcp را اجرا کن و جریانِ ورود در مرورگر را دنبال کن.

override کردنِ discoveryِ متادیتای OAuth

Claude Code را به یک URLِ متادیتای authorization serverِ مشخصِ OAuth اشاره بده تا زنجیره‌ی discoveryِ پیش‌فرض را دور بزنی. وقتی endpointهای استانداردِ سرورِ MCP خطا می‌دهند، یا وقتی می‌خواهی discovery را از طریقِ یک پراکسیِ داخلی هدایت کنی، authServerMetadataUrl را تنظیم کن. به‌صورتِ پیش‌فرض، Claude Code اول RFC 9728 Protected Resource Metadata را در /.well-known/oauth-protected-resource بررسی می‌کند، بعد به RFC 8414 authorization server metadata در /.well-known/oauth-authorization-server برمی‌گردد.

authServerMetadataUrl را در شیءِ oauthِ پیکربندیِ سرورت در .mcp.json تنظیم کن:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

URL باید از https:// استفاده کند. authServerMetadataUrl به Claude Code نسخه‌ی v2.1.64 یا بالاتر نیاز دارد. مقدارِ scopes_supportedِ این URLِ متادیتا، scopeهایی را که سرورِ upstream تبلیغ می‌کند override می‌کند.

محدود کردنِ scopeهای OAuth

oauth.scopes را تنظیم کن تا scopeهایی را که Claude Code در جریانِ authorization درخواست می‌کند pin کنی. این روشِ پشتیبانی‌شده برای محدود کردنِ یک سرورِ MCP به زیرمجموعه‌ی موردِتأییدِ تیمِ امنیت است، وقتی authorization serverِ upstream scopeهای بیشتری از آنچه می‌خواهی اعطا کنی تبلیغ می‌کند. مقدار یک رشته‌ی واحدِ جداشده با فاصله است، که با قالبِ پارامترِ scope در RFC 6749 §3.3 می‌خواند.

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

oauth.scopes بر هم authServerMetadataUrl و هم scopeهایی که سرور در /.well-known discover می‌کند تقدم دارد. آن را تنظیم‌نشده بگذار تا سرورِ MCP خودش مجموعه‌ی scopeِ درخواستی را تعیین کند.

اگر authorization server مقدارِ offline_access را در scopes_supported تبلیغ کند، Claude Code آن را به scopeهای pin‌شده اضافه می‌کند تا access token بدونِ یک ورودِ مرورگریِ جدید قابلِ refresh باشد.

اگر سرور بعداً برای یک فراخوانِ ابزار یک 403 insufficient_scope برگرداند، Claude Code با همان scopeهای pin‌شده دوباره احراز هویت می‌کند. وقتی ابزاری که نیاز داری به scopeای خارج از pin احتیاج دارد، oauth.scopes را گسترده‌تر کن.

اگر سرورِ MCPت از طرحِ احراز هویتی غیر از OAuth استفاده می‌کند (مثلِ Kerberos، توکن‌های کوتاه‌عمر، یا یک SSOِ داخلی)، از headersHelper استفاده کن تا headerهای درخواست را هنگامِ اتصال بسازی. Claude Code آن دستور را اجرا می‌کند و خروجی‌اش را با headerهای اتصال merge می‌کند.

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

دستور می‌تواند inline هم باشد:

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"
    }
  }
}

الزامات:

دستور باید یک شیءِ JSON از جفت‌های کلید-مقدارِ رشته‌ای را به stdout بنویسد
دستور در یک shell با timeoutِ ۱۰ ثانیه‌ای اجرا می‌شود
headerهای پویا هر headersِ ثابت با همان نام را override می‌کنند

این helper در هر اتصال (در آغازِ نشست و هنگامِ اتصالِ مجدد) تازه اجرا می‌شود. هیچ caching‌ای نیست، پس اسکریپتت خودش مسئولِ هرگونه استفاده‌ی مجدد از توکن است.

Claude Code هنگامِ اجرای helper این متغیرهای محیطی را تنظیم می‌کند:

متغیر	مقدار
`CLAUDE_CODE_MCP_SERVER_NAME`	نامِ سرورِ MCP
`CLAUDE_CODE_MCP_SERVER_URL`	URLِ سرورِ MCP

از این‌ها استفاده کن تا یک اسکریپتِ helperِ واحد بنویسی که به چند سرورِ MCP سرویس بدهد.

افزودنِ سرورهای MCP از پیکربندیِ JSON

اگر یک پیکربندیِ JSON برای یک سرورِ MCP داری، می‌توانی مستقیماً اضافه‌اش کنی:

افزودنِ یک سرورِ MCP از JSON

# Basic syntax
claude mcp add-json <name> '<json>'

# Example: Adding an HTTP server with JSON configuration
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# Example: Adding a stdio server with JSON configuration
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

# Example: Adding an HTTP server with pre-configured OAuth credentials
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

تأییدِ اینکه سرور اضافه شد

claude mcp get weather-api

واردکردنِ سرورهای MCP از Claude Desktop

اگر قبلاً سرورهای MCP را در Claude Desktop پیکربندی کرده‌ای، می‌توانی واردشان کنی:

واردکردنِ سرورها از Claude Desktop

# Basic syntax
claude mcp add-from-claude-desktop

انتخابِ اینکه کدام سرورها وارد شوند

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

تأییدِ اینکه سرورها وارد شدند

claude mcp list

استفاده از سرورهای MCP از Claude.ai

اگر با یک حسابِ Claude.ai واردِ Claude Code شده‌ای، سرورهای MCPای که در Claude.ai اضافه کرده‌ای به‌صورتِ خودکار در Claude Code در دسترس‌اند:

پیکربندیِ سرورهای MCP در Claude.ai

سرورها را در claude.ai/customize/connectors اضافه کن. در پلن‌های Team و Enterprise، فقط ادمین‌ها می‌توانند سرور اضافه کنند.

احراز هویتِ سرورِ MCP

هر گامِ احراز هویتِ موردِنیاز را در Claude.ai کامل کن.

دیدن و مدیریتِ سرورها در Claude Code

در Claude Code، از این دستور استفاده کن:

/mcp

سرورهای Claude.ai در فهرست با نشانه‌هایی ظاهر می‌شوند که می‌گویند از Claude.ai می‌آیند.

از نسخه‌ی v2.1.161، کانکتورهایی که هرگز به آن‌ها sign in نکرده‌ای، پشتِ یک ردیفِ Show unused connectors در انتهای بخشِ claude.ai جمع می‌شوند، تا یک فهرستِ تأمین‌شده توسطِ سازمان پنل را پر نکند. آن ردیف را انتخاب کن تا بازشان کنی. کانکتوری که قبلاً به آن sign in کرده‌ای، حتی وقتی الان به احراز هویتِ مجدد نیاز دارد، قابلِ‌مشاهده می‌ماند.

کانکتورهای Claude.ai فقط وقتی fetch می‌شوند که روشِ احراز هویتِ فعالت اشتراکِ Claude.aiات باشد. وقتی ANTHROPIC_API_KEY، ANTHROPIC_AUTH_TOKEN، apiKeyHelper، یا یک ارائه‌دهنده‌ی شخصِ ثالث مثلِ Bedrock یا Vertex فعال باشد، بارگذاری نمی‌شوند، حتی اگر قبلاً /login را اجرا کرده باشی. اگر /mcp کانکتوری را که اضافه کرده‌ای فهرست نکرد، /status را اجرا کن تا تأیید کنی کدام روشِ احراز هویت فعال است، آن متغیرِ محیطی را unset کن یا تنظیمِ apiKeyHelper را بردار، بعد /login را اجرا کن تا حسابِ Claude.aiات را انتخاب کنی.

سروری که در Claude Code اضافه کرده‌ای بر یک کانکتورِ claude.ai که به همان URL اشاره می‌کند تقدم دارد. وقتی این اتفاق بیفتد، /mcp کانکتور را به‌عنوانِ پنهان فهرست می‌کند و نشان می‌دهد اگر ترجیح می‌دهی از کانکتور استفاده کنی، چطور تکراری را برداری.

بعضی کانکتورهای میزبانی‌شده توسطِ Anthropic، مثلِ Microsoft 365، Gmail و Google Calendar، از OAuthِ محلی از Claude Code پشتیبانی نمی‌کنند چون ارائه‌دهنده‌ی هویتِ upstream فقط redirect URLای را که claude.ai ثبت کرده می‌پذیرد. از نسخه‌ی v2.1.162، احراز هویتِ یکی از این میزبان‌ها در /mcp پیامی نشان می‌دهد که به‌جایش هدایتت می‌کند تا آن را در Settings → Connectors روی claude.ai وصل کنی. وقتی آنجا وصل شد، کانکتور به‌صورتِ خودکار در Claude Code ظاهر می‌شود.

برای غیرفعال کردنِ سرورهای MCPِ claude.ai در Claude Code، متغیرِ محیطیِ ENABLE_CLAUDEAI_MCP_SERVERS را روی false تنظیم کن:

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

استفاده از Claude Code به‌عنوانِ یک سرورِ MCP

می‌توانی خودِ Claude Code را به‌عنوانِ یک سرورِ MCP استفاده کنی که اپلیکیشن‌های دیگر بتوانند به آن وصل شوند:

# Start Claude as a stdio MCP server
claude mcp serve

می‌توانی این را در Claude Desktop با افزودنِ این پیکربندی به claude_desktop_config.json استفاده کنی:

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

پیکربندیِ مسیرِ فایلِ اجرایی: فیلدِ command باید به فایلِ اجراییِ Claude Code ارجاع دهد. اگر دستورِ claude در PATHِ سیستمت نباشد، باید مسیرِ کاملِ فایلِ اجرایی را مشخص کنی.

برای یافتنِ مسیرِ کامل:

which claude

بعد مسیرِ کامل را در پیکربندی‌ات به کار ببر:

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "/full/path/to/claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

بدونِ مسیرِ درستِ فایلِ اجرایی، با خطاهایی مثلِ spawn claude ENOENT روبه‌رو می‌شوی.

حدها و هشدارهای خروجیِ MCP

وقتی ابزارهای MCP خروجی‌های بزرگ تولید می‌کنند، Claude Code به مدیریتِ مصرفِ توکن کمک می‌کند تا کانتکستِ گفت‌وگوی تو پُر نشود:

آستانه‌ی هشدارِ خروجی: وقتی خروجیِ هر ابزارِ MCP از ۱۰٬۰۰۰ توکن بیشتر شود، Claude Code هشدار نشان می‌دهد
حدِ قابلِ‌پیکربندی: می‌توانی بیشینه‌ی توکن‌های خروجیِ مجازِ MCP را با متغیرِ محیطیِ MAX_MCP_OUTPUT_TOKENS تنظیم کنی
حدِ پیش‌فرض: بیشینه‌ی پیش‌فرض ۲۵٬۰۰۰ توکن است
دامنه: متغیرِ محیطی به ابزارهایی اعمال می‌شود که حدِ خودشان را اعلام نمی‌کنند. ابزارهایی که anthropic/maxResultSizeChars را تنظیم می‌کنند، برای محتوای متنی به‌جایش از آن مقدار استفاده می‌کنند، صرف‌نظر از اینکه MAX_MCP_OUTPUT_TOKENS روی چه مقداری تنظیم شده. ابزارهایی که داده‌ی تصویری برمی‌گردانند همچنان تابعِ MAX_MCP_OUTPUT_TOKENS هستند

برای بالا بردنِ حد برای ابزارهایی که خروجی‌های بزرگ تولید می‌کنند:

export MAX_MCP_OUTPUT_TOKENS=50000
claude

این به‌ویژه وقتی مفید است که با سرورهای MCPی کار می‌کنی که:

از مجموعه‌داده‌ها یا پایگاه‌داده‌های بزرگ کوئری می‌گیرند
گزارش‌ها یا مستنداتِ مفصل تولید می‌کنند
فایل‌های لاگِ گسترده یا اطلاعاتِ دیباگ را پردازش می‌کنند

بالا بردنِ حد برای یک ابزارِ مشخص

اگر داری یک سرورِ MCP می‌سازی، می‌توانی به تک‌تکِ ابزارها اجازه دهی نتایجی بزرگ‌تر از آستانه‌ی پیش‌فرضِ persist-to-disk برگردانند، با تنظیمِ _meta["anthropic/maxResultSizeChars"] در ورودیِ پاسخِ tools/listِ آن ابزار. Claude Code آستانه‌ی آن ابزار را تا مقدارِ یادداشت‌شده، تا سقفِ سختِ ۵۰۰٬۰۰۰ کاراکتر، بالا می‌برد.

این برای ابزارهایی مفید است که خروجی‌هایی ذاتاً بزرگ اما ضروری برمی‌گردانند، مثلِ schemaهای پایگاه‌داده یا درختِ کاملِ فایل‌ها. بدونِ این یادداشت، نتایجی که از آستانه‌ی پیش‌فرض بیشتر شوند روی دیسک persist می‌شوند و در گفت‌وگو با یک ارجاعِ فایل جایگزین می‌شوند.

{
  "name": "get_schema",
  "description": "Returns the full database schema",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

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

پاسخ به درخواست‌های elicitationِ MCP

سرورهای MCP می‌توانند با استفاده از elicitation در میانه‌ی کار از تو ورودیِ ساختارمند بخواهند. وقتی سروری به اطلاعاتی نیاز دارد که خودش نمی‌تواند به‌دست آورد، Claude Code یک دیالوگِ تعاملی نشان می‌دهد و پاسخت را به سرور پس می‌دهد. سمتِ تو هیچ پیکربندی‌ای لازم نیست: دیالوگ‌های elicitation وقتی سروری درخواست کند خودکار ظاهر می‌شوند.

سرورها می‌توانند به دو روش ورودی بخواهند:

حالتِ فرم: Claude Code یک دیالوگ با فیلدهای فرمِ تعریف‌شده توسطِ سرور نشان می‌دهد (مثلاً promptِ نام‌کاربری و رمز). فیلدها را پر کن و ارسال کن.
حالتِ URL: Claude Code یک URLِ مرورگری برای احراز هویت یا تأیید باز می‌کند. جریان را در مرورگر کامل کن، بعد در CLI تأیید کن.

برای پاسخِ خودکار به درخواست‌های elicitation بدونِ نشان دادنِ دیالوگ، از هوکِ Elicitation استفاده کن.

اگر داری یک سرورِ MCP می‌سازی که از elicitation استفاده می‌کند، برای جزئیاتِ پروتکل و نمونه‌های schema مشخصاتِ elicitationِ MCP را ببین.

استفاده از منابعِ MCP

سرورهای MCP می‌توانند منابعی را در معرض بگذارند که می‌توانی با @ mentionها به آن‌ها ارجاع دهی، شبیه به اینکه چطور به فایل‌ها ارجاع می‌دهی.

ارجاع به منابعِ MCP

فهرستِ منابعِ در دسترس

در پرامپتت @ تایپ کن تا منابعِ در دسترس از همه‌ی سرورهای MCPِ متصل را ببینی. منابع در کنارِ فایل‌ها در منوی تکمیلِ خودکار ظاهر می‌شوند.

ارجاع به یک منبعِ مشخص

از قالبِ @server:protocol://resource/path برای ارجاع به یک منبع استفاده کن:

Can you analyze @github:issue://123 and suggest a fix?

Please review the API documentation at @docs:file://api/authentication

ارجاع به چند منبع

می‌توانی در یک پرامپتِ واحد به چند منبع ارجاع دهی:

Compare @postgres:schema://users with @docs:file://database/user-model

مقیاس‌پذیری با جست‌وجوی ابزارِ MCP

جست‌وجوی ابزار با به‌تعویق‌انداختنِ تعریفِ ابزارها تا وقتی Claude به آن‌ها نیاز دارد، مصرفِ کانتکستِ MCP را پایین نگه می‌دارد. در آغازِ نشست فقط نامِ ابزارها و دستورالعمل‌های سرور بارگذاری می‌شوند، پس افزودنِ سرورهای MCPِ بیشتر تأثیرِ کمی بر پنجره‌ی کانتکستت دارد. Claude Code سقفِ ثابتی برای تعدادِ ابزار به‌ازای هر سرور تحمیل نمی‌کند؛ حدِ عملی بودجه‌ی پنجره‌ی کانتکستِ توست.

چطور کار می‌کند

جست‌وجوی ابزار به‌صورتِ پیش‌فرض فعال است. ابزارهای MCP به‌جای اینکه از همان اول در کانتکست بار شوند، به تعویق می‌افتند، و Claude وقتی کاری به آن‌ها نیاز داشته باشد از یک ابزارِ جست‌وجو برای کشفِ ابزارهای مرتبط استفاده می‌کند. فقط ابزارهایی که Claude واقعاً استفاده می‌کند واردِ کانتکست می‌شوند. از دیدِ تو، ابزارهای MCP دقیقاً مثلِ قبل کار می‌کنند.

اگر بارگذاریِ مبتنی‌بر آستانه را ترجیح می‌دهی، ENABLE_TOOL_SEARCH=auto را تنظیم کن تا وقتی schemaها در ۱۰٪ پنجره‌ی کانتکست جا می‌شوند از همان اول بار شوند و فقط مازاد به تعویق بیفتد. برای همه‌ی گزینه‌ها پیکربندیِ جست‌وجوی ابزار را ببین.

برای نویسندگانِ سرورِ MCP

اگر داری یک سرورِ MCP می‌سازی، فیلدِ دستورالعمل‌های سرور با فعال بودنِ جست‌وجوی ابزار مفیدتر می‌شود. دستورالعمل‌های سرور به Claude کمک می‌کنند بفهمد کِی برای ابزارهایت جست‌وجو کند، شبیه به اینکه چطور اسکیل‌ها کار می‌کنند.

دستورالعمل‌های سرورِ روشن و توصیفی اضافه کن که این‌ها را توضیح دهند:

ابزارهایت چه دسته‌ای از کارها را مدیریت می‌کنند
Claude کِی باید برای ابزارهایت جست‌وجو کند
قابلیت‌های کلیدی‌ای که سرورت فراهم می‌کند

Claude Code توضیحاتِ ابزار و دستورالعمل‌های سرور را هرکدام در ۲KB کوتاه می‌کند. کوتاه نگهشان دار تا از کوتاه‌شدن جلوگیری کنی، و جزئیاتِ حیاتی را نزدیکِ آغاز بگذار.

پیکربندیِ جست‌وجوی ابزار

جست‌وجوی ابزار به‌صورتِ پیش‌فرض فعال است: ابزارهای MCP به تعویق می‌افتند و بنا به نیاز کشف می‌شوند. Claude Code آن را روی Vertex AI به‌صورتِ پیش‌فرض غیرفعال می‌کند. همچنین وقتی ANTHROPIC_BASE_URL به یک میزبانِ غیرِ first-party اشاره می‌کند غیرفعال است، چون بیشترِ پراکسی‌ها بلاک‌های tool_reference را فوروارد نمی‌کنند. ENABLE_TOOL_SEARCH را صریحاً تنظیم کن تا هر کدام از این fallbackها را override کنی.

جست‌وجوی ابزار نیازمندِ مدلی است که از بلاک‌های tool_reference پشتیبانی کند. مدل‌های Haiku از آن پشتیبانی نمی‌کنند. روی Vertex AI، جست‌وجوی ابزار برای Claude Sonnet 4.5 و بالاتر و Claude Opus 4.5 و بالاتر پشتیبانی می‌شود.

رفتارِ جست‌وجوی ابزار را با متغیرِ محیطیِ ENABLE_TOOL_SEARCH کنترل کن:

مقدار	رفتار
(تنظیم‌نشده)	همه‌ی ابزارهای MCP به تعویق می‌افتند و بنا به نیاز بار می‌شوند. روی Vertex AI یا وقتی `ANTHROPIC_BASE_URL` یک میزبانِ غیرِ first-party باشد به بارگذاریِ از-همان-اول برمی‌گردد
`true`	همه‌ی ابزارهای MCP به تعویق می‌افتند. Claude Code حتی روی Vertex AI و از طریقِ پراکسی‌ها headerِ beta را می‌فرستد. روی مدل‌های Vertex AIِ پیش از Sonnet 4.5 یا Opus 4.5، یا روی پراکسی‌هایی که از بلاک‌های `tool_reference` پشتیبانی نمی‌کنند، درخواست‌ها شکست می‌خورند
`auto`	حالتِ آستانه: اگر ابزارها در ۱۰٪ پنجره‌ی کانتکست جا شوند از همان اول بار می‌شوند، وگرنه به تعویق می‌افتند
`auto:N`	حالتِ آستانه با درصدِ سفارشی، که در آن `N` بینِ ۰ تا ۱۰۰ است. برای مثال، `auto:5` برای ۵٪
`false`	همه‌ی ابزارهای MCP از همان اول بار می‌شوند، بدونِ تعویق

# Use a custom 5% threshold
ENABLE_TOOL_SEARCH=auto:5 claude

# Disable tool search entirely
ENABLE_TOOL_SEARCH=false claude

یا مقدار را در فیلدِ envِ settings.json تنظیم کن.

می‌توانی به‌طور خاص خودِ ابزارِ ToolSearch را هم غیرفعال کنی:

{
  "permissions": {
    "deny": ["ToolSearch"]
  }
}

معاف کردنِ یک سرور از تعویق

اگر ابزارهای یک سرور باید همیشه برای Claude بدونِ گامِ جست‌وجو قابلِ‌مشاهده باشند، alwaysLoad را در پیکربندیِ آن سرور روی true تنظیم کن. آن‌وقت هر ابزارِ آن سرور صرف‌نظر از تنظیمِ ENABLE_TOOL_SEARCH در آغازِ نشست واردِ کانتکست می‌شود. این را برای تعدادِ کمی ابزار که Claude در هر نوبت به آن‌ها نیاز دارد به کار ببر، چون هر ابزارِ از-همان-اول کانتکستی را مصرف می‌کند که وگرنه برای گفت‌وگوی تو در دسترس بود.

ورودیِ .mcp.jsonِ زیر یک سرورِ HTTP را معاف می‌کند و بقیه‌ی سرورها را در حالتِ تعویق نگه می‌دارد:

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

فیلدِ alwaysLoad روی همه‌ی نوع‌های سرور در دسترس است و به Claude Code نسخه‌ی v2.1.121 یا بالاتر نیاز دارد. یک سرورِ MCP می‌تواند با گنجاندنِ "anthropic/alwaysLoad": true در شیءِ _metaِ ابزار، تک‌تکِ ابزارها را هم به‌عنوانِ always-loaded علامت بزند، که برای آن ابزار همان اثر را دارد.

تنظیمِ alwaysLoad: true همچنین راه‌اندازی را تا وقتی سرور وصل شود بلاک می‌کند، با سقفِ timeoutِ اتصالِ استانداردِ ۵ ثانیه‌ای. این اعمال می‌شود حتی با اینکه راه‌اندازیِ MCP در غیرِ این صورت به‌صورتِ پیش‌فرض non-blocking است، چون ابزارها باید وقتی اولین پرامپت ساخته می‌شود حاضر باشند. بقیه‌ی سرورها همچنان در پس‌زمینه وصل می‌شوند.

استفاده از پرامپت‌های MCP به‌عنوانِ دستور

سرورهای MCP می‌توانند پرامپت‌هایی را در معرض بگذارند که در Claude Code به‌عنوانِ دستور در دسترس می‌شوند.

اجرای پرامپت‌های MCP

کشفِ پرامپت‌های در دسترس

/ تایپ کن تا همه‌ی دستورهای در دسترس، از جمله آن‌هایی که از سرورهای MCP می‌آیند، را ببینی. پرامپت‌های MCP با قالبِ /mcp__servername__promptname ظاهر می‌شوند.

اجرای یک پرامپت بدونِ آرگومان

/mcp__github__list_prs

اجرای یک پرامپت با آرگومان

بسیاری از پرامپت‌ها آرگومان می‌پذیرند. آن‌ها را جداشده با فاصله بعد از دستور پاس بده:

/mcp__github__pr_review 456

/mcp__jira__create_issue "Bug in login flow" high

پیکربندیِ مدیریت‌شده‌ی MCP

برای سازمان‌هایی که به کنترلِ متمرکز بر اینکه کاربران به کدام سرورهای MCP می‌توانند وصل شوند نیاز دارند، پیکربندیِ مدیریت‌شده‌ی MCP را ببین. آن صفحه استقرارِ یک مجموعه‌ی ثابتِ سرور با managed-mcp.json، محدود کردنِ سرورها با allowedMcpServers و deniedMcpServers، و اینکه کاربران وقتی سروری بلاک می‌شود چه می‌بینند را پوشش می‌دهد.