
در این آموزش، اتصال سرور MCP به Claude را قدم به قدم و با مثالهایی از اسناد رسمی Anthropic توضیح می دهیم. فرض کنید ابزاری دارید که نتایج آن را بهتر است هوش مصنوعی ببیند. پروتکل MCP این کار را ممکن می کند. بنابراین Claude می تواند ابزارها را پیدا کند و در طول مکالمه از آنها استفاده کند. البته هر ابزاری که متصل می کنید، مجوز خواندن یا تغییر داده های مرتبط را هم می گیرد. در نتیجه باید فقط سرورهایی را وصل کنید که به آنها اعتماد دارید.
MCP مخفف Model Context Protocol است. این پروتکل مشخص می کند یک کلاینت چگونه با سرور ابزارها صحبت کند. شما می توانید سرور را از راه دور روی HTTPS اجرا کنید، یا به صورت محلی روی همان کامپیوتر کار کند. در حالت دوم، Claude برنامه را خودش اجرا می کند و با آن از طریق ورودی و خروجی استاندارد حرف می زند. ما در ادامه هر دو حالت را بررسی می کنیم.
اتصال سرور MCP به Claude Code از راه دور
Claude Code ابزار خط فرمان Anthropic است. اگر تازه آن را نصب کرده اید، مطالعه آموزش دستیار هوش مصنوعی در ترمینال هم مفید است. برای اضافه کردن یک سرور HTTP کافی است دستور زیر را اجرا کنید:
claude mcp add --transport http scalar-docs https://scalar.com/mcp
claude mcp get scalar-docs
claude mcp list
شکل کلی دستور به صورت claude mcp add --transport http <name> <url> است. نام، برچسب دلخواه شماست. سپس با دستور claude mcp list فهرست سرورها را ببینید. داخل جلسه هم دستور /mcp وضعیت و ابزارهای هر سرور را نشان می دهد. برای امتحان، می توانید بپرسید: «با استفاده از scalar-docs توضیح بده passthrough چگونه کار می کند». اولین بار Claude از شما اجازه می گیرد.
وقتی سرور به ورود نیاز دارد
بسیاری از سرورها از OAuth استفاده می کنند. برای این سرورها همان دستور بالا را بدون هیچ توکنی اجرا کنید. وقتی Claude Code کد 401 بگیرد، سرور را نیازمند احراز هویت علامت گذاری می کند. سپس /mcp را باز کنید، سرور را انتخاب کنید و وارد شوید. می توانید از شل هم با claude mcp login my-server وارد شوید. Claude Code توکن ها را به صورت خودکار ذخیره و تمدید می کند. برای خروج، claude mcp logout my-server را اجرا کنید.
برای سرورهایی که کلید API می گیرند، هدر را با --header بدهید. دقت کنید که الگوریتم درخواستی سرور را هم بنویسید. برای توکن Bearer، کلمه Bearer و یک فاصله قبل از توکن لازم است:
claude mcp add --transport http my-api https://mcp.example.com/mcp \
--header "Authorization: Bearer $MY_API_TOKEN"
اگر هدر نادرست باشد، Claude Code اتصال را ناموفق اعلام می کند و به OAuth روی نمی آورد. بنابراین اگر می خواستید وارد شوید، هدر را حذف کنید. هنگام چسباندن توکن، فاصله اضافه اول و آخر را هم برطرف کنید.
اتصال سرور MCP به Claude و اشتراک گذاری تنظیمات
شما هر سرور را در یکی از سه محدوده ذخیره می کنید. محدوده Local به صورت پیش فرض است و فقط برای شما و فقط در همان پروژه است. در محدوده User تنها خودتان حساب دارید، ولی تنظیمات در همه پروژه ها دردسترس است. سومین گزینه یعنی Project را در فایل .mcp.json می نویسید و با تیم خود به اشتراک می گذارید. انتخاب محدوده با پارامتر --scope انجام می شود:
claude mcp add --transport http scalar-docs --scope project https://scalar.com/mcp
پس از آن فایل .mcp.json شبیه مثال زیر است:
{
"mcpServers": {
"scalar-docs": {
"type": "http",
"url": "https://scalar.com/mcp"
}
}
}
همکاران شما با باز کردن پروژه، ابتدا تایید می کنند که سرورها را بپذیرند. هرگز توکن را مستقیم در این فایل ننویسید. به جای آن از متغیر محیطی استفاده کنید. Claude Code جایگزینی متغیرها را در url، headers، command، args و env پشتیبانی می کند:
{
"mcpServers": {
"my-api": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"headers": { "Authorization": "Bearer ${MY_API_TOKEN}" }
}
}
}
هر کاربر توکن خود را در شل تنظیم می کند. عبارت ${VAR:-default} هم مقدار پیش فرض می دهد. نکته امنیتی جالب اینکه Claude Code متغیرهای اعتباری خود مانند ANTHROPIC_API_KEY را در url و هدر سرورهای راه دور خالی می خواند. بنابراین یک فایل پروژه نمی تواند اعتبارنامه Claude شما را به سرور دیگری بفرستد.
اضافه کردن سرور محلی
برای سرور محلی، دستور اجرا بعد از دو خط تیره می آید. هرچه بعد از -- می نویسید دست مستقیم به سرور می رسد و قبل از آن مخصوص Claude Code است. متغیرها هم با --env تعریف می شوند:
claude mcp add galaxy --env GALAXY_API_TOKEN=your-token -- npx tsx /path/to/planets.ts
اگر از macOS یا WSL استفاده می کنید و سرورها در Claude Desktop تعریف شده اند، دستور claude mcp add-from-claude-desktop آنها را وارد می کند. از مسیرهای مطلق استفاده کنید تا بعداً دچار خطای مسیر نشوید.
اتصال سرور MCP به Claude در claude.ai و اپلیکیشن ها
در claude.ai، Claude Desktop و اپ موبایل، به سرورها «connector» می گویند. شما اتصال سرور MCP به Claude را در اینجا با ساختن custom connector انجام می دهید. کانکتورهای سفارشی روی پلن رایگان هم دردسترس هستند، ولی پلن رایگان فقط یک کانکتور می پذیرد. پلن های Pro، Max، Team و Enterprise محدودیت بیشتری ندارند.
در پلن Free، Pro یا Max به مسیر Customize سپس Connectors بروید. گزینه Add custom connector را بزنید، آدرس سرور مثل https://scalar.com/mcp را وارد کنید و دوباره Add و سپس Connect را انتخاب کنید. اگر سرور از OAuth استفاده می کند، اطلاعات ثبت شده را در تنظیمات احراز هویت وارد کنید؛ در غیر این صورت آنها را خالی بگذارید.
در پلن Team یا Enterprise، Owner از مسیر Organization settings سپس Connectors اقدام می کند. گزینه Add، سپس Custom و سپس Web را انتخاب کنید. اعضا کانکتور را با برچسب Custom می بینند و با زدن Connect وارد حساب خود می شوند. سه حالت احراز هویت در پنجره کانکتور وجود دارد: ورود الان، ورود وقتی سرور درخواست کرد، یا بدون ورود.
برای سرورهایی که کلید ثابت می گیرند، Anthropic بخشی به نام Request headers را مستند کرده است. این قابلیت بتا است و فقط در سازمان های مشخصی دیده می شود. حتماً الگوریتم Authorization را خودتان بنویسید، چون Claude مقدار هدر را دقیقاً همانطور که تایپ کرده اید ارسال می کند. تنظیمات احراز هویت بعد از اضافه کردن کانکتور قابل ویرایش نیستند؛ باید آن را حذف و دوباره اضافه کنید.
مدیریت کانکتورها در مکالمه
درون مکالمه، منوی + و سپس Connectors را باز کنید تا کانکتورها را برای همان چت روشن یا خاموش کنید. از مسیر Customize سپس Connectors می توانید ابزارهای اضافی را روی حالت Blocked بگذارید. این کار برای ابزارهایی که قابلیت نوشتن دارند و نیازی به آنها ندارید، توصیه می کنیم.
اتصال سرور MCP به Claude Desktop برای سرورهای محلی
سرورهای راه دور در Claude Desktop همان کانکتورهای بالا هستند. سرورهای محلی فرق می کنند، چون خود اپلیکیشن آنها را اجرا می کند و تنها موقع شروع شدن تنظیمات را می خواند. دو راه وجود دارد. راه ساده، نصب فایل .mcpb است؛ آن را به صفحه Settings سپس Extensions بکشید.
راه دوم، ویرایش فایل تنظیمات است. از منوی Claude در نوار منوی سیستم، نه تنظیمات داخل چت، گزینه Settings، سپس Developer و سپس Edit Config را بزنید. محل فایل claude_desktop_config.json به شرح زیر است:
- مک:
~/Library/Application Support/Claude/claude_desktop_config.json - ویندوز:
%APPDATA%\Claude\claude_desktop_config.json
سرورها را زیر کلید mcpServers اضافه کنید:
{
"mcpServers": {
"galaxy": {
"command": "npx",
"args": ["tsx", "/Users/you/mcp/planets.ts"],
"env": { "GALAXY_API_TOKEN": "your-token" }
}
}
}
بعد از ذخیره فایل، Claude Desktop را کاملاً ببندید و دوباره باز کنید. لاگ ها در مک داخل ~/Library/Logs/Claude و در ویندوز داخل %APPDATA%\Claude\logs قرار دارند. فایل mcp.log و فایلی با نام mcp-server-<name>.log خروجی استاندارد هر سرور را نشان می دهند.
مثال عملی: سرور میزبانی شده توسط Scalar
وقتی در Scalar یک سرور MCP برای API خود می سازید، آدرس نصب به شکل https://mcp.scalar.com/mcp/YOUR_INSTALL_ID است. Scalar سرور را میزبانی می کند و چیزی برای اجرا روی سرور شما وجود ندارد. نحوه اتصال بستگی به تنظیمات دسترسی installation دارد. سه حالت رایج را در جدول زیر می بینید:
| حالت installation | نحوه اتصال | احراز هویت |
|---|---|---|
| خصوصی (پیش فرض) | آدرس را بدون هدر اضافه کنید | OAuth یا Personal Access Token |
| عمومی با passthrough | آدرس را همراه هدر دلخواه اضافه کنید | هر کاربر اعتبار API خود را می دهد |
| عمومی با OAuth passthrough | آدرس را بدون هدر اضافه کنید | ورود به سرور مجوز API خودتان |
برای حالت خصوصی دستور claude mcp add --transport http my-api https://mcp.scalar.com/mcp/YOUR_INSTALL_ID را اجرا کنید، سپس /mcp را باز کرده و وارد شوید. در claude.ai همان آدرس را به عنوان کانکتور وارد کنید. اعضای تیم می توانند از Personal Access Token موجود در Account سپس API Keys استفاده کنند.
در حالت passthrough عمومی، هدری را که موقع تنظیم سرور تعیین کرده اید بدهید. Scalar آن هدر را بدون ذخیره کردن به سمت API می فرستد. در حالت OAuth passthrough، مرورگر به جای صفحه Scalar، صفحه ورود API شما را باز می کند. یک راه سریع برای تشخیص حالت هم وجود دارد: حالت خصوصی و OAuth passthrough هر دو به درخواست بدون احراز هویت با کد 401 و هدر WWW-Authenticate پاسخ می دهند. سند metadata که آن هدر به آن اشاره می کند، مشخص می کند سرور مجوز کدام است. شناسه installation اشتباه هم با کد 404 پاسخ می دهد.
پس از اتصال، سوالی بپرسید که به API نیاز داشته باشد، مثل «پنج سفارش آخر را فهرست کن». ابزارهای Scalar به Claude کمک می کنند توصیف API را جستجو کند و فقط عملیات لازم را اجرا کند.
اتصال سرور MCP به Claude از طریق Agent SDK
اگر Agent خودتان را می سازید، می توانید سرورها را در گزینه های Claude Agent SDK تعریف کنید. نمونه زیر از مستندات Scalar گرفته شده و یک installation را به تنظیمات MCP تبدیل می کند:
import { query } from '@anthropic-ai/claude-agent-sdk'
import { agentScalar } from '@scalar/agent'
const scalar = agentScalar({ token: 'your-personal-token' })
const installation = await scalar.installation('your-installation-id')
for await (const message of query({
prompt: 'Which endpoints let me create a planet?',
options: {
mcpServers: { scalar: installation.createAnthropicMCP() },
allowedTools: ['mcp__scalar__*'],
},
})) {
if ('result' in message) console.log(message.result)
}
راه دیگر، استفاده از MCP connector در Messages API است که تماس مستقیم با سرورهای راه دور را ممکن می کند. اگر مطمئن نیستید اصلاً به MCP نیاز دارید یا یک کتابخانه تایپ شده کافی است، مقایسه MCP و SDK را مطالعه کنید. سپس بر اساس نیازتان یکی را انتخاب کنید.
برای آشنایی بیشتر با اصول پروتکل و نحوه کار سرورهای محلی، اسناد رسمی MCP در مستندات Claude Code مرجع خوبی است. همچنین مطالعه آموزش مبتدیان Claude به شما کمک می کند تا با رابط کلی این دستیار آشنا شوید.
رفع مشکلات رایج اتصال سرور MCP به Claude
گاهی یک سرور با وجود تنظیم درست کار نمی کند. جدول زیر رایج ترین پیام ها و دلیل آنها را خلاصه می کند:
| پیام یا وضعیت | علت احتمالی | راه حل |
|---|---|---|
| url هست ولی type نیست | سرور به اشتباه Local خوانده شده | اضافه کنید: “type”: “http” |
| Pending approval | سرور .mcp.json تایید نشده | وارد پروژه شوید و تایید کنید |
| 401 یا needs authentication | توکن منقضی یا هدر ناقص | /mcp و ورود مجدد، یا اصلاح Bearer |
| هدر ${VAR} خالی می رسد | متغیر تعریف نشده یا جزو متغیرهای محفوظ است | نام متغیر را عوض کنید |
| کانکتور در claude.ai وصل نمی شود | سرور در شبکه خصوصی است | سرور را عمومی کنید یا از tunnel استفاده کنید |
| نتایج ابزار بریده می شود | بیش از ۱۰ هزار توکن هشدار و ۲۵ هزار توکن محدودیت | MAX_MCP_OUTPUT_TOKENS را بالا ببرید |
| سرور کند است و timeout می دهد | زمان راه اندازی کوتاه است | MCP_TIMEOUT یا timeout در .mcp.json |
Anthropic کانکتورهای سفارشی را از فضای ابری خود می خواند، نه از لپ تاپ شما. بنابراین سروری که پشت VPN یا فایروال است به عنوان کانکتور کار نخواهد کرد. اگر سرور باید خصوصی بماند، Anthropic راه حل MCP tunnels را پیشنهاد می کند. برای بررسی مشکلات سطح پروتکل هم می توانید سرور را خارج از Claude با MCP Inspector امتحان کنید.
سوالات متداول
چگونه سرور MCP را به Claude Code اضافه کنم؟ برای سرور راه دور، claude mcp add --transport http و سپس نام و آدرس را بدهید. برای سرور محلی، نام، سپس -- و سپس دستور اجرا را بنویسید. گزینه --scope project تنظیمات را در فایل .mcp.json به اشتراک می گذارد. وضعیت را با claude mcp list یا /mcp ببینید.
آیا می شود از MCP در نسخه رایگان Claude استفاده کرد؟ بله. کانکتورهای سفارشی راه دور روی پلن رایگان دردسترس هستند، ولی فقط یک کانکتور مجاز است. پلن های Pro، Max، Team و Enterprise می توانند چندین کانکتور داشته باشند. سرورهای محلی Claude Desktop و Claude Code را جداگانه تنظیم می کنید.
فایل تنظیمات Claude Desktop کجاست؟ در مک داخل ~/Library/Application Support/Claude/claude_desktop_config.json و در ویندوز داخل %APPDATA%\Claude\claude_desktop_config.json است. بعد از ویرایش، Claude Desktop را کاملاً ببندید و دوباره باز کنید.
آیا کانکتورهای claude.ai در Claude Code هم کار می کنند؟ بله، وقتی Claude Code با حساب claude.ai وارد شده باشد. کانکتورها خودکار در /mcp ظاهر می شوند. ولی وقتی Claude Code با کلید API یا ارائه دهنده دیگری احراز هویت شود، این کانکتورها بارگذاری نمی شوند.
آیا Claude می تواند به سرور MCP روی localhost وصل شود؟ به عنوان کانکتور سفارشی، خیر. Anthropic کانکتورها را از فضای ابری خود می خواند، پس سرور محلی برای آنها قابل دسترس نیست. از Claude Code یا سرور محلی Claude Desktop استفاده کنید، یا سرور را در جایی عمومی مستقر کنید.
خلاصه: اتصال سرور MCP به Claude
اتصال سرور MCP به Claude بستگی به محصولی دارد که استفاده می کنید. در Claude Code از دستور claude mcp add و در اپلیکیشن ها از custom connector استفاده می کنید. سرورهای محلی Claude Desktop را با فایل claude_desktop_config.json تعریف می کنید. بنابراین قبل از اتصال، حتماً آدرس سرور، روش احراز هویت و میزان اعتماد به ناشر آن را بررسی کنید. در نتیجه ابزارهای زیادی را بدون نیاز به کدنویسی اضافه می کنید. در پایان، با دستور /mcp وضعیت را چک کنید و تنها ابزارهای مورد نیاز را فعال بگذارید.
