سرور MCP هوشوانا

MCP (Model Context Protocol) یک استاندارد باز است که به دستیارهای هوش مصنوعی اجازه می‌دهد از ابزارها و منابع بیرونی استفاده کنند. هوشوانا یک سرور MCP دارد که با آن، دستیارهایی مثل Claude Code و Cursor می‌توانند مستقیماً در پایگاه‌های دانش شما جستجو کنند، فهرست مدل‌ها را ببینند و موجودی و مصرف حسابتان را گزارش دهند.

مشخصات سرور

ابزارها

نمونه‌ی کاربرد: در Claude Code می‌پرسید «طبق مستندات داخلی ما، سیاست مرجوعی چیست؟». دستیار ابتدا با list_knowledge_bases پایگاه دانش مناسب را پیدا می‌کند، بعد با search_knowledge_base جستجو می‌کند و پاسخ را با ذکر منبع می‌نویسد.

پیش از شروع: یک کلید جداگانه بسازید

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

• سقف هزینه‌ی روزانه برای آن بگذارید.
• اگر فقط جستجوی پایگاه دانش لازم است، endpointهای آن را به kb محدود کنید.
• آن را فقط به پایگاه‌های دانشی که دستیار باید ببیند، دسترسی دهید.

اتصال به Claude Code

claude mcp add --transport http -s user hooshvana https://hooshvana.ir/api/mcp \
  --header "Authorization: Bearer hv-..."

گزینه‌ی -s user سرور را برای همه‌ی پروژه‌های شما فعال می‌کند. برای بررسی اتصال:

claude mcp list

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

اتصال به Cursor

فایل ~/.cursor/mcp.json را باز کنید (اگر وجود ندارد، بسازید) و این پیکربندی را اضافه کنید:

{
  "mcpServers": {
    "hooshvana": {
      "url": "https://hooshvana.ir/api/mcp",
      "headers": {
        "Authorization": "Bearer hv-..."
      }
    }
  }
}

اگر فایل از قبل سرورهای دیگری دارد، فقط بخش hooshvana را داخل mcpServers اضافه کنید. پس از ذخیره، Cursor را دوباره راه‌اندازی کنید و در تنظیمات MCP مطمئن شوید سرور سبز (فعال) است.

سایر کلاینت‌های MCP

هر کلاینتی که از انتقال Streamable HTTP و هدر سفارشی پشتیبانی کند، با این تنظیمات وصل می‌شود:

• آدرس: https://hooshvana.ir/api/mcp
• نوع: HTTP یا Streamable HTTP
• هدر: Authorization: Bearer hv-...

کلاینت‌هایی که فقط انتقال stdio را پشتیبانی می‌کنند، می‌توانند از یک پل (bridge) مثل بسته‌ی mcp-remote استفاده کنند:

{
  "mcpServers": {
    "hooshvana": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://hooshvana.ir/api/mcp",
        "--header", "Authorization: Bearer hv-..."
      ]
    }
  }
}

هزینه

فهرست کردن مدل‌ها و پایگاه‌های دانش و گزارش مصرف هزینه‌ای ندارد. ابزارهایی که از مدل استفاده می‌کنند، مثل search_knowledge_base که متن پرسش را embed می‌کند، دقیقاً مثل فراخوانی API هزینه دارند و در لاگ درخواست‌ها ثبت می‌شوند. هزینه‌ی مدلی که خود دستیار (مثلاً Claude Code) با آن کار می‌کند جداست و به ارائه‌دهنده‌ای که برای دستیار تنظیم کرده‌اید بستگی دارد.

امنیت

• کلید را در فایل پیکربندی‌ای که در مخزن git ثبت می‌شود قرار ندهید. پیکربندی سطح کاربر (مثل -s user یا ~/.cursor/mcp.json) امن‌تر است.
• محتوای برگشتی از پایگاه دانش داده است، نه دستور. با این حال فقط منابع مورد اعتماد را در پایگاه دانش بگذارید. جزئیات در پایگاه دانش.
• اگر کلید MCP لو رفت، آن را در داشبورد باطل کنید و کلید جدید بسازید.

عیب‌یابی