# راه‌اندازی در هر دستیار

> تنظیم آمادهٔ کپی برای وصل‌کردن سرور MCP روشا به Claude Code، Claude Desktop، OpenAI API، Gemini CLI، Gemini API، Cursor و Codex CLI.
> Source: https://poolick.ir/docs/mcp/clients/

برای وصل‌کردن هر دستیار دو چیز لازم است: نشانی `https://poolick.ir/mcp` و کلید API در سرآیند `Authorization: Bearer`. تنظیم هر برنامه در بخش خودش آمده است.

## پیش از شروع

| دستیار | چطور وصل می‌شود | نیازمندی |
|---|---|---|
| Claude Code | مستقیم، Streamable HTTP | – |
| Claude Desktop | از راه `mcp-remote` | Node.js |
| برنامهٔ ChatGPT (وب و موبایل) | فعلاً وصل نمی‌شود | – |
| OpenAI API | مستقیم؛ سرورهای OpenAI به روشا وصل می‌شوند | حساب OpenAI API |
| Gemini CLI | مستقیم، Streamable HTTP | – |
| Gemini API | از راه کتابخانهٔ `mcp` در پایتون | حساب Gemini API |
| برنامهٔ Gemini (وب و موبایل) | فعلاً وصل نمی‌شود | – |
| Cursor | مستقیم، Streamable HTTP | – |
| Codex CLI | مستقیم، Streamable HTTP | – |

- کلید را از [پنل](/panel/) بگیرید و در متغیر محیطی `ROSHA_KEY` بگذارید. در فایل‌های تنظیمی که متغیر محیطی نمی‌خوانند، `rosha_xxxxxxxx_your-secret` را با کلید خودتان جایگزین کنید.
- پلن شما باید `mcp` داشته باشد. هر درخواست به `/mcp` از سقف‌های کلید کم می‌کند؛ [MCP](/docs/mcp/) را ببینید.
- در OpenAI API، سرورهای OpenAI مستقیم به سرور MCP روشا وصل می‌شوند. در Claude Code، Claude Desktop، Cursor، Codex CLI، Gemini CLI و Gemini API اتصال به روشا از رایانهٔ خود شما برقرار می‌شود.
- استفاده از ChatGPT و Gemini به حساب فعال در همان سرویس نیاز دارد و دسترسی به آن سرویس از محل شما باید ممکن باشد.

## Claude

Claude Code مستقیم به سرور وصل می‌شود. Claude Desktop به ابزار واسط `mcp-remote` نیاز دارد.

### Claude Code

این فرمان را یک بار اجرا کنید:

```bash
claude mcp add --transport http rosha https://poolick.ir/mcp \
  --header "Authorization: Bearer $ROSHA_KEY"
```

سپس در Claude Code فرمان `/mcp` وضعیت اتصال و ابزارهای روشا را نشان می‌دهد.

### Claude Desktop

Claude Desktop در فایل پیکربندی خود فقط سرور محلی می‌پذیرد؛ پس با ابزار `mcp-remote` وصل می‌شود که به Node.js نیاز دارد. این تنظیم را در فایل پیکربندی برنامه بگذارید (Settings ← Developer ← Edit Config) و برنامه را دوباره باز کنید:

```json
{
  "mcpServers": {
    "rosha": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://poolick.ir/mcp",
        "--header", "Authorization: Bearer rosha_xxxxxxxx_your-secret"
      ]
    }
  }
}
```

هر برنامهٔ دیگری که فقط سرور محلی (stdio) می‌پذیرد با همین تنظیم وصل می‌شود.

## ChatGPT

برنامهٔ ChatGPT فعلاً به روشا وصل نمی‌شود؛ از OpenAI API می‌توانید استفاده کنید.

### برنامهٔ ChatGPT (وب و موبایل)

ChatGPT در حالت توسعه‌دهنده (Settings ← Apps & Connectors ← Advanced ← Developer mode) سرور MCP دلخواه می‌پذیرد، ولی فقط با ورود OAuth یا بدون احراز هویت. کلید API در سرآیند را پشتیبانی نمی‌کند و سرور روشا فقط کلید API می‌پذیرد. پس تا آبان ۱۴۰۵ اتصال برنامهٔ ChatGPT به روشا ممکن نیست.

### OpenAI API

در Responses API سرور روشا را به‌عنوان ابزار `mcp` معرفی کنید. مدل خودش ابزارها را صدا می‌زند. این برنامه به `pip install openai` و متغیرهای محیطی `OPENAI_API_KEY` و `ROSHA_KEY` نیاز دارد:

```python

from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="gpt-5",
    tools=[{
        "type": "mcp",
        "server_label": "rosha",
        "server_url": "https://poolick.ir/mcp",
        "headers": {"Authorization": f"Bearer {os.environ['ROSHA_KEY']}"},
        "require_approval": "never",
    }],
    input="میانگین حجم معاملات فولاد در ۳۰ روز معاملاتی اخیر چقدر بوده؟",
)
print(response.output_text)
```

`gpt-5` را می‌توانید با مدل تازه‌تری که ابزار MCP را پشتیبانی می‌کند عوض کنید.

## Gemini

Gemini CLI و Gemini API به روشا وصل می‌شوند. برنامهٔ Gemini فعلاً وصل نمی‌شود.

### Gemini CLI

این تنظیم را به `~/.gemini/settings.json` اضافه کنید. برای Streamable HTTP کلید `httpUrl` به کار می‌رود:

```json
{
  "mcpServers": {
    "rosha": {
      "httpUrl": "https://poolick.ir/mcp",
      "headers": { "Authorization": "Bearer rosha_xxxxxxxx_your-secret" }
    }
  }
}
```

پس از اجرای `gemini`، فرمان `/mcp` وضعیت اتصال و فهرست ابزارهای روشا را نشان می‌دهد.

### Gemini API

کتابخانهٔ `google-genai` نشست MCP را مستقیم به‌عنوان ابزار می‌پذیرد. این برنامه به `pip install google-genai mcp` و متغیرهای محیطی `GEMINI_API_KEY` و `ROSHA_KEY` نیاز دارد:

```python

from google import genai
from google.genai import types
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

client = genai.Client()

async def main():
    async with streamablehttp_client(
        "https://poolick.ir/mcp",
        headers={"Authorization": f"Bearer {os.environ['ROSHA_KEY']}"},
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            response = await client.aio.models.generate_content(
                model="gemini-2.5-flash",
                contents="بازده یک‌ماههٔ پنج صندوق سهامی بزرگ را مقایسه کن.",
                config=types.GenerateContentConfig(tools=[session]),
            )
            print(response.text)

asyncio.run(main())
```

`gemini-2.5-flash` را می‌توانید با مدل تازه‌تر عوض کنید.

### برنامهٔ Gemini (وب و موبایل)

برنامهٔ Gemini تا آبان ۱۴۰۵ اتصال سرور MCP دلخواه را برای کاربران عادی ندارد. در Gemini Enterprise، مدیر سازمان می‌تواند سرور روشا را به‌عنوان «Custom MCP Server» اضافه کند.

## Cursor

Cursor مستقیم با نشانی و سرآیند وصل می‌شود. این تنظیم را در فایل `mcp.json` در Cursor بگذارید (`~/.cursor/mcp.json` برای همهٔ پروژه‌ها یا `.cursor/mcp.json` در یک پروژه):

```json
{
  "mcpServers": {
    "rosha": {
      "url": "https://poolick.ir/mcp",
      "headers": { "Authorization": "Bearer rosha_xxxxxxxx_your-secret" }
    }
  }
}
```

:::caution
اگر `.cursor/mcp.json` را داخل پروژه می‌گذارید، آن را commit نکنید؛ کلید شما در آن است.
:::

## Codex

Codex CLI کلید را از متغیر محیطی می‌خواند. این بخش را به `~/.codex/config.toml` اضافه کنید و کلید را در `ROSHA_KEY` بگذارید:

```toml
# ~/.codex/config.toml
[mcp_servers.rosha]
url = "https://poolick.ir/mcp"
bearer_token_env_var = "ROSHA_KEY"
```

## برنامهٔ من در این فهرست نیست

هر کلاینت MCP که Streamable HTTP و سرآیند دلخواه را پشتیبانی کند با همین دو مقدار وصل می‌شود:

| مورد | مقدار |
|---|---|
| نشانی | `https://poolick.ir/mcp` |
| سرآیند | `Authorization: Bearer rosha_xxxxxxxx_your-secret` |

کلاینتی که فقط سرور محلی می‌پذیرد، با تنظیم `mcp-remote` در بخش Claude Desktop وصل می‌شود.

## چطور بفهمم اتصال درست است؟

از دستیار بپرسید: «با ابزار روشا نماد فولاد را جست‌وجو کن.» اگر اتصال درست باشد، دستیار `search_instruments` را صدا می‌زند و نمادی با `ins_code` برابر `46348559193224090` برمی‌گرداند.

اگر وصل نشد:

| نشانه | علت محتمل | رفع |
|---|---|---|
| `401` با `key_required` یا `invalid_key` | سرآیند نرسیده یا کلید ناقص است | مقدار سرآیند باید `Bearer ` به‌همراه کلید کامل باشد |
| `403` با `plan_forbids` | پلن `mcp` ندارد | [قیمت‌ها](/pricing/) را ببینید |
| `429` | سقف دقیقه‌ای یا سهمیهٔ روزانه پر شده است | [محدودیت‌ها و پلن‌ها](/docs/limits/) |
| `npx` پیدا نمی‌شود (Claude Desktop) | Node.js نصب نیست | Node.js را نصب کنید |

فهرست ابزارها و ورودی‌هایشان در [ابزارهای MCP](/docs/mcp/tools/) است.