چطور در کدکس سرور MCP با client secret را وصل کنیم

کدکس از نسخه‌ی 0.158.0 در فرمان codex mcp add سوییچ --oauth-client-secret را می‌پذیرد. یعنی یک سرور MCP که فقط با client registration از پیش ثبت‌شده کار می‌کند — مثل Figma، که ثبت خودکار ندارد — دیگر کنار گذاشتنی نیست و لازم نیست دستی در config.toml بنویسید. در این مقاله همین یک فرمان را روی همین سرور اجرا می‌کنیم و خروجی واقعی‌اش را می‌بینیم.

در این نوشته

کابل‌های شبکه که به یک درگاه وصل شده‌اند، همان چیزی که اتصال کدکس به یک سرور دوردست انجام می‌دهد. عکس: پکسلز — عکاس: Nothing Ahead — https://www.pexels.com/photo/network-adapter-with-wires-on-wall-7400884/

چه چیزی در 0.158.0 عوض شد
اتصال سرور با کلاینت ثبت‌شده
پیکربندی ذخیره‌شده را چطور ببینیم
سرورهای بی‌مجوز و STDIO
چهار اشتباهی که این مسیر را خراب می‌کنند
اگر تازه با MCP شروع می‌کنید

چه چیزی در 0.158.0 عوض شد

کدکس نسخه‌ی 0.158.0 را در ۲۸ سپتامبر ۲۰۲۶ منتشر کرد: فهرست تغییرات کدکس کلی‌ایس‌الی. در فهرست قابلیت‌های تازه، سومین سطر دقیقاً همین است: اتصال به سرورهای MCP که client secret از پیش ثبت‌شده می‌خواهند، از جمله از مسیر codex mcp add --oauth-client-secret، در پی‌آر 47891.

این یک قابلیت کوچک به نظر می‌رسد، ولی یک دسته‌ی کامل از سرورهای سازمانی را از حالت غیرقابل اتصال بیرون می‌آورد. پیش از این نسخه سه راه برای وصل کردن یک سرور HTTP به کدکس داشتید: bearer_token_env_var برای توکن استاتیک، یا ثبت خودکار کلاینت با DCR و CIMD که در آن سرور خودش کلاینت می‌سازد. راه سوم برای سروری که روی یک دامنه‌ی ثبت‌شده میزبانی می‌شود کار می‌کند، اما سروری که فقط با یک جفت client_id و client_secret از پیش ساخته‌شده کار می‌کند، هیچ‌کدام از این دو مسیر را قبول نمی‌کند.

تفاوت را می‌شود بدون خواندن هیچ مقاله‌ای اندازه گرفت. همان فرمان را روی نسخه‌ی قبلی اجرا کنید و خطای کلاینت خط فرمان را ببینید. لحظه‌ی خواندن: ۲۹ سپتامبر ۲۰۲۶.

# نسخه‌ی قبلی را نصب می‌کنیم تا خطای واقعی را ببینیم
$ npm install -g @openai/codex@0.157.0
$ codex --version
codex-cli 0.157.0

# سوییچ تازه روی این نسخه وجود ندارد
$ codex mcp add probe157 --url https://mcp.figma.com/mcp --oauth-client-secret "x"
error: unexpected argument '--oauth-client-secret' found

  tip: a similar argument exists: '--oauth-client-id'
  tip: to pass '--oauth-client-secret' as a value, use '-- --oauth-client-secret'

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

اتصال سرور با کلاینت ثبت‌شده

اول نسخه‌ی تازه را نصب کنید. بسته روی npm منتشر می‌شود و همان عددی را می‌پذیرد که در مستندات آمده است.

# نصب نسخه‌ی تازه روی همان ماشین
$ npm install -g @openai/codex@0.158.0
added 2 packages in 9s
$ codex --version
codex-cli 0.158.0

حالا سرور را اضافه کنید. برای نمونه از Figma استفاده می‌کنیم، چون سرور MCP آن عمومی است، client_id می‌خواهد، و جریان authorization مخصوص خودش را دارد. دو سوییچ پایین یک جفت‌اند: یکی شناسه، یکی رمز.

# شناسه و رمز کلاینتی که در پنل ارائه‌دهنده ساخته‌ایم
$ codex mcp add figma --url https://mcp.figma.com/mcp \
    --oauth-client-id hoosh-demo-4821 \
    --oauth-client-secret "s3cr3t-demo-value"
Added global MCP server 'figma'.
OAuth callback URL: http://127.0.0.1/callback
Detected OAuth support. Starting OAuth flow…

Authorize `figma` by opening this URL in your browser:
https://www.figma.com/oauth/mcp?response_type=code&client_id=hoosh-demo-4821
  &state=YUVeXajH5jFGEIBdeWQpyg
  &code_challenge=CvfQpRASknQtNHFlmsyuanwz6o2b0OMK28yZa5rPVK8
  &code_challenge_method=S256
  &redirect_uri=http%3A%2F%2F127.0.0.1%3A36633%2Fcallback
  &scope=mcp%3Aconnect

سه چیز را در همین خروجی ببینید. اول، callback_url دقیقاً همان مقدار ثابت http://127.0.0.1/callback است که مستندات MCP کدکس برای کلاینت‌های از پیش ثبت‌شده اعلام می‌کند؛ این همان رشته‌ای است که باید در پنل ارائه‌دهنده ثبت کنید. دوم، کدکس بلافاصله بعد از add جریان authorization را شروع می‌کند، حتی اگر شما فقط می‌خواستید پیکربندی را بنویسید. سوم، شماره‌ی پورت ۳۶۶۳۳ در redirect_uri پویا است و در هر اجرا عوض می‌شود.

روی سرور بی‌مرس یا داخل کانتینر، باز شدن مرورگر شکست می‌خورد و کدکس همان هشدار را می‌دهد. برای همین فرمان login سوییچ --no-browser دارد که نشانی را چاپ می‌کند و به‌جای باز کردن مرورگر، نشانی بازگشتی را از شما می‌گیرد. هر دو اجرا را در عمل دیده‌ام و متن‌های زیر واقعی‌اند.

$ codex mcp login figma --no-browser
Authorize the MCP server by opening this URL in your browser:
https://www.figma.com/oauth/mcp?response_type=code&client_id=hoosh-demo-4821
  &state=DyKut81-DXlxwh51QmAL0w
  &code_challenge=qUE-pTYbIeMD9Lx0YHRLFpmYDlkvyMpU6pNeZfG5Y68
  &code_challenge_method=S256
  &redirect_uri=http%3A%2F%2F127.0.0.1%3A38131%2Fcallback

After signing in, copy the full URL from your browser's address bar.
If the callback page cannot load, paste that URL here anyway.
Callback URL (input hidden):

دو عدد را کنار هم بگذارید. پورت redirect_uri در اجرای اول ۳۶۶۳۳ و در اجرای دوم ۳۸۱۳۱ بود. این دقیقاً همان چیزی است که بخش 7.3 از RFC 8252 اجازه می‌دهد: سرور مجوز باید پورت‌های متغیر روی لوپ‌بک را بپذیرد. اگر ارائه‌دهنده‌ی شما فقط یک پورت ثابت را قبول کند، این جریان در همان مرحله می‌شکند.

پیکربندی ذخیره‌شده را چطور ببینیم

کدکس بلافاصله بعد از افزودن، فایل ~/.codex/config.toml را می‌نویسد و مقادیر را دقیقاً به همان شکلی که داده‌اید می‌ریزد. این فایل تمام حقیقت پیکربندی است؛ فرمان‌های بعدی فقط همین را می‌خوانند.

$ cat ~/.codex/config.toml
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"

[mcp_servers.figma.oauth]
client_id = "hoosh-demo-4821"
client_secret = "s3cr3t-demo-value"
callback_url = "http://127.0.0.1/callback"

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

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

$ codex mcp list
Name        Url                        Bearer Token Env Var  Status   Auth
figma       https://mcp.figma.com/mcp  -                     enabled  Not logged in

$ codex mcp get figma
figma
  enabled: true
  transport: streamable_http
  url: https://mcp.figma.com/mcp
  bearer_token_env_var: -
  http_headers: -
  env_http_headers: -
  http_headers_helper: -
  remove: codex mcp remove figma

ستون Auth سه حالت متفاوت را نشان می‌دهد و فرقشان معنادار است. برای سرور figma نوشته Not logged in، یعنی پیکربندی درست است ولی جریان مجوز کامل نشده. برای یک سرور STDIO مثل Context7 نوشته Unsupported، چون اصلاً بحث مجوز در آن مطرح نیست. برای یک سرور HTTP که پاسخ OAuth تبلیغ نمی‌شود، می‌نویسد Unknown، یعنی کدکس نمی‌داند بدون وارد شدن کار می‌کند یا نه و باید حدس بزنید.

سرورهای بی‌مجوز و STDIO

همان مسیر add برای سرورهای دیگر هم کار می‌کند و فرقشان در جریان مجوز معلوم می‌شود. سرور STDIO یک فرمان است، نه یک نشانی، و کدکس اصلاً سراغ جریان مجوز نمی‌رود.

$ codex mcp add ctx7 -- npx -y @upstash/context7-mcp
Added global MCP server 'ctx7'.

$ codex mcp add plain-http --url http://127.0.0.1:9/mcp
Added global MCP server 'plain-http'.
MCP server may or may not require login. Run `codex mcp login plain-http` to login.

تفاوت در یک جمله است: سرور STDIO در یک خط تمام شد، ولی سرور HTTP بعد از ذخیره یک هشدار درباره‌ی مجوز چاپ کرد. -- در فرمان STDIO مرز بین سوییچ‌های کدکس و فرمان سرور است؛ بدون آن، npx را کدکس به‌عنوان یک سوییچ خودش می‌خواند و خطا می‌دهد.

نوع سرور	جریان مجوز	ستون Auth
HTTP با کلاینت ثبت‌شده	بله، با PKCE روی لوپ‌بک	Not logged in
HTTP با توکن استاتیک	ندارد	Not logged in
HTTP بی‌مجوز	هشدار می‌دهد	Unknown
STDIO	ندارد	Unsupported

سطر دوم جدول از مستندات کدکس برداشته شده: auth را روی oauth می‌گذارید تا از اعتبارنامه‌های ذخیره‌شده استفاده شود، و bearer_token_env_var نام متغیر محیطی توکن را می‌گیرد. برای سرورهای تیمی این تنظیم در config.toml مشترک می‌ماند و کدکس آن را روی همه‌ی کلاینت‌های یک میزبان می‌خواند، پس توکن داخل فایل پیکربندی نوشته نمی‌شود. فرمان کامل هر نوع، دو خط پیش‌تر آمده است: --url برای سرورهای HTTP و -- به‌دنبال نام سرور برای STDIO.

چهار اشتباهی که این مسیر را خراب می‌کنند

اشتباه در سمت پیکربندی

اولین اشتباه، کامیت کردن ~/.codex/config.toml است، چون client_secret در آن به‌صورت متن ساده می‌نشیند. آن را در .gitignore بگذارید یا فقط بخش oauth را در فایل نمونه‌ی تیمی بگذارید، نه فایل واقعی را.

اشتباه دوم، ثبت یک پورت ثابت در پنل ارائه‌دهنده است. هر اجرا یک پورت تازه می‌سازد، پس پنل باید لوپ‌بک بدون پورت را بپذیرد. اگر ارائه‌دهنده این را رد کند، خطا در همان گام اول می‌آید و پیام خطا درباره‌ی iss یا شناسه صادرکننده است، نه درباره‌ی رمز شما.

اشتباه در سمت فرمان و کلاینت

اشتباه سوم، نوشتن --oauth-secret به‌جای --oauth-client-secret است. همان خطای 0.157.0 بالا نشان می‌دهد که کلاینت خط فرمان چه می‌گوید، و نکته‌ی مهم اینجاست: این خطا پیش از هر ارتباطی با سرور ظاهر می‌شود، پس اگر آن را دیدید، مشکل از نسخه‌ی نصب‌شده است، نه از تنظیمات سرور.

اشتباه چهارم، نداشتن کنترل روی کلاینت OAuth است. کلاینت ثبت‌شده معمولاً یک شناسه‌ی ثابت و طولانی‌عمر است، پس اگر از آن در چند پروژه و چند تیم استفاده کنید، عملاً یک کلید مشترک دارید. برای هر محیط یک شناسه‌ی جدا بسازید و callback_url را دقیقاً همان رشته‌ای ثبت کنید که کدکس چاپ می‌کند.

اگر تازه با MCP شروع می‌کنید

اگر هنوز سروری ندارید، مسیر کوتاه‌تری هست. در پست تست سرور MCP با خط فرمان اینسپکتور توضیح داده‌ام چطور یک سرور را بدون نوشتن هیچ کلاینتی، پیش از اضافه کردن به کدکس، آزمایش کنید.

برای دیدن فهرست کامل قابلیت‌های نسخه‌ی 0.158.0، مقایسه‌ی دو نسخه در گیت‌هاب و صفحه‌ی بسته در npm هر دو مسیر مستقیم‌اند. اگر می‌خواهید بدانید این نسخه در کدام کلاینت‌ها و با چه محدودیتی عرضه می‌شود، صفحه‌ی رسمی کدکس در وب‌سایت OpenAI مرجع نهایی است. برند می‌تواند در حال حاضر غیرفعال باشد؛ اگر codex mcp list ستون Auth را نشان نداد، یعنی نسخه‌ی شما قدیمی‌تر از 0.158.0 است و باید همان فرمان نصب را اجرا کنید.