سرور MCP گیسو همان وبسرویس گیسو است که به زبان Model Context Protocol حرف میزند. برنامههایی مثل Claude Code، Cursor، VS Code و Cline به آن وصل میشوند و ابزارهایش (پرسیدن از مدل دیگر، ساخت تصویر، گفتار، موسیقی و ویدیو) را در اختیار مدل خودشان میگذارند. کلید، اعتبار، محدودیتها و صورتحساب همان وبسرویس است. معرفی سادهتر و راهنمای هر برنامه: صفحهٔ سرور MCP.
پروتکل و انتقال
- انتقال: Streamable HTTP، فقط پاسخ JSON. هر
POSTیک پیام JSON-RPC 2.0 (یا یک دسته) میگیرد و یک پاسخ JSON برمیگرداند؛ جریان SSE باز نمیشود. - نسخهها:
2025-06-18،2025-03-26،2024-11-05. درinitializeنسخهای را که میخواهید بفرستید؛ اگر نشناسیم، تازهترین را جواب میدهیم. - بدون نشست: سرور حالتی نگه نمیدارد و
Mcp-Session-Idنمیدهد. هر درخواست کلید خودش را دارد. GETپاسخ405میدهد (پیام خودجوشی از سرور نمیآید) وDELETEپاسخ204.- اعلانها (
notifications/*) پاسخ202بدون بدنه میگیرند.pingنتیجهٔ خالی میدهد. - تواناییها فقط
toolsاست؛resources/listوprompts/listفهرست خالی برمیگردانند. نام سرور درserverInfo:gisoo.
احراز هویت
کلید API گیسو (sk-gisoo-v1-… یا sk-ntz-v1-…) را در سربرگ Authorization: Bearer بفرستید؛ سربرگ X-API-Key هم پذیرفته میشود.
بررسی کلید همان بررسی وبسرویس است: کلید باطل، منقضی یا غیرفعال، فهرست IP مجاز و پروژهٔ غیرفعال همانجا رد میشوند. کلید را در بخش API اپ میسازید.
سرور با کلید کار میکند و ورود با OAuth ندارد. برنامهای که فقط OAuth بلد است (مثل اتصال MCP در ChatGPT) فعلاً وصل نمیشود. Claude Desktop هم در فایل تنظیماتش فقط برنامهٔ محلی اجرا میکند؛ برای آن از mcp-remote استفاده کنید (پایینتر).
برای سرورها و کاربران داخل ایران، در این نمونه نشانی gisoo.pro را با ir.gisoo.pro جایگزین کنید؛ مسیر و کلید هماناند.
curl https://gisoo.pro/api/mcp \
-H "Authorization: Bearer $GISOO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "initialize",
"params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "curl", "version": "1"}}}'
ابزارها
۸ ابزار. ابزارهای پولی در annotations با readOnlyHint: false علامت خوردهاند تا برنامه پیش از اجرا از کاربر بپرسد.
هر ابزار پولی یک درخواست عادی وبسرویس است و در گزارش مصرف با همان endpoint دیده میشود.
| ابزار | کار | هزینه | معادل در وبسرویس |
|---|---|---|---|
list_models |
مدلهایی که کلید شما اجازه دارد، با قیمت دلاری هر کدام؛ بدون هزینه. | رایگان | GET /models |
ask_model |
یک پرسش را به یکی از مدلهای گفتوگوی گیسو (GPT، Claude، Gemini، DeepSeek و…) میفرستد؛ برای نظر دوم یا ترجمه. | از اعتبار، بهاندازهٔ مصرف | POST /chat/completions |
generate_image |
یک تصویر از روی توضیح متنی میسازد و همانجا در برنامهٔ شما نشانش میدهد. | از اعتبار، بهاندازهٔ مصرف | POST /images/generations |
text_to_speech |
متن فارسی یا انگلیسی را به فایل صوتی (MP3) تبدیل میکند. | از اعتبار، بهاندازهٔ مصرف | POST /audio/speech |
generate_music |
یک قطعهٔ کوتاه موسیقی از روی توضیح سبک و حالوهوا میسازد (MP3). | از اعتبار، بهاندازهٔ مصرف | POST /audio/music |
create_video |
ساخت یک ویدیوی کوتاه را شروع میکند و شناسهٔ کار را برمیگرداند. | از اعتبار، بهاندازهٔ مصرف | POST /videos |
get_video |
وضعیت ساخت ویدیو و، پس از پایان، نشانی دانلود فایل MP4؛ بدون هزینه. | رایگان | GET /videos/{id} |
account_balance |
موجودی اعتبار، مصرف همین کلید و سقف هزینهاش؛ بدون هزینه. | رایگان | GET /me |
list_models
مدلهایی که کلید شما اجازه دارد، با قیمت دلاری هر کدام؛ بدون هزینه.
توضیحی که برنامه به مدل نشان میدهد:
List the AI models this Gisoo key may call, with their public USD prices. Filter by type (chat, image, speech, transcription, music, video, embedding) and/or a search word. Free: costs nothing. Use the returned `id` as the `model` argument of the other tools.
فهرست مدلهایی که این کلید اجازهٔ استفاده از آنها را دارد، با قیمت دلاری؛ این ابزار هزینه ندارد.
60.{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"chat",
"image",
"speech",
"transcription",
"music",
"video",
"embedding"
],
"description": "Kind of model. Omit for all."
},
"search": {
"type": "string",
"description": "Part of the model id or name, e.g. \"gemini\", \"claude\", \"deepseek\"."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 60
}
}
}
ask_model
یک پرسش را به یکی از مدلهای گفتوگوی گیسو (GPT، Claude، Gemini، DeepSeek و…) میفرستد؛ برای نظر دوم یا ترجمه.
توضیحی که برنامه به مدل نشان میدهد:
Send one prompt to any chat model on Gisoo (GPT, Claude, Gemini, DeepSeek, Grok, Qwen…) and get its answer, for example to get a second opinion or a translation. Paid from the Gisoo credit of this key, exactly like POST /chat/completions; the cost in USD is reported at the end of the answer. Find model ids with list_models (e.g. gemini-3.6-flash, deepseek-v4-flash, gpt-4o-mini).
یک پرسش را به یکی از مدلهای گفتوگوی گیسو میفرستد و پاسخش را برمیگرداند؛ هزینه از اعتبار گیسو کم میشود.
2048.{
"type": "object",
"properties": {
"model": {
"type": "string",
"description": "Chat model id from list_models."
},
"prompt": {
"type": "string",
"description": "The full question, with any context the model needs: it sees nothing else."
},
"system": {
"type": "string",
"description": "Optional system instruction, e.g. \"Answer in Persian.\""
},
"max_tokens": {
"type": "integer",
"minimum": 1,
"maximum": 8192,
"default": 2048
},
"temperature": {
"type": "number",
"minimum": 0,
"maximum": 2
}
},
"required": [
"model",
"prompt"
]
}
generate_image
یک تصویر از روی توضیح متنی میسازد و همانجا در برنامهٔ شما نشانش میدهد.
توضیحی که برنامه به مدل نشان میدهد:
Create one image from a text description and return it as an MCP image (base64). Default model gemini-3.1-flash-lite-image at 1024x1024, a quick and inexpensive one; name another image model from list_models for higher quality. Paid from the Gisoo credit of this key like POST /images/generations; the USD cost is in the text. Text written inside the image is unreliable, especially Persian: leave it out and add it later.
یک تصویر از روی توضیح متنی میسازد؛ هزینه از اعتبار گیسو کم میشود.
{
"type": "object",
"properties": {
"prompt": {
"type": "string",
"description": "What the image shows. English or Persian."
},
"model": {
"type": "string",
"description": "Image model id. Default: gemini-3.1-flash-lite-image."
},
"size": {
"type": "string",
"description": "e.g. 1024x1024 (default), 1536x1024, 1024x1536. Larger costs more."
},
"quality": {
"type": "string",
"enum": [
"low",
"medium",
"high",
"auto"
],
"description": "GPT Image models only. Higher costs more."
}
},
"required": [
"prompt"
]
}
text_to_speech
متن فارسی یا انگلیسی را به فایل صوتی (MP3) تبدیل میکند.
توضیحی که برنامه به مدل نشان میدهد:
Turn up to 2000 characters of text (Persian or English) into spoken audio, returned as an MCP audio block (base64, MP3 by default). Default model gpt-4o-mini-tts. Paid from the Gisoo credit of this key like POST /audio/speech; the USD cost is in the text.
متن را به فایل صوتی تبدیل میکند؛ هزینه از اعتبار گیسو کم میشود.
"mp3".{
"type": "object",
"properties": {
"input": {
"type": "string",
"maxLength": 2000,
"description": "The text to read aloud."
},
"model": {
"type": "string",
"description": "Speech model id. Default: gpt-4o-mini-tts."
},
"voice": {
"type": "string",
"description": "Voice name, e.g. alloy, nova (OpenAI) or Kore, Puck (Gemini). Optional."
},
"instructions": {
"type": "string",
"description": "How to read it, e.g. \"calm, slow\". Models that support it only."
},
"response_format": {
"type": "string",
"enum": [
"mp3",
"wav",
"opus",
"aac",
"flac"
],
"default": "mp3"
}
},
"required": [
"input"
]
}
generate_music
یک قطعهٔ کوتاه موسیقی از روی توضیح سبک و حالوهوا میسازد (MP3).
توضیحی که برنامه به مدل نشان میدهد:
Compose one short piece of music from a description (genre, mood, instruments, optional lyrics) and return it as an MCP audio block (base64 MP3). Default model lyria-3-clip-preview (a short clip). Takes up to about a minute. Paid per piece from the Gisoo credit of this key like POST /audio/music; the USD cost is in the text.
یک قطعهٔ کوتاه موسیقی از روی توضیح میسازد؛ هزینه از اعتبار گیسو کم میشود.
{
"type": "object",
"properties": {
"prompt": {
"type": "string",
"maxLength": 4000,
"description": "Genre, mood, tempo, instruments; lyrics if wanted."
},
"model": {
"type": "string",
"description": "Music model id. Default: lyria-3-clip-preview."
}
},
"required": [
"prompt"
]
}
create_video
ساخت یک ویدیوی کوتاه را شروع میکند و شناسهٔ کار را برمیگرداند.
توضیحی که برنامه به مدل نشان میدهد:
Start rendering a short video from a text description. Returns a job id at once; a render takes one to a few minutes. Poll get_video with that id until status is "completed". Default model veo-3.1-lite at its shortest length. Paid per second of video from the Gisoo credit of this key, charged when the render starts and refunded in full if it fails, exactly like POST /videos.
ساخت ویدیو را شروع میکند و شناسهٔ کار را برمیگرداند؛ وضعیت را با get_video بپرسید.
{
"type": "object",
"properties": {
"prompt": {
"type": "string",
"maxLength": 4000,
"description": "The scene: subject, action, camera, light, sound."
},
"model": {
"type": "string",
"description": "Video model id. Default: veo-3.1-lite."
},
"seconds": {
"type": "integer",
"description": "Length in seconds. Allowed values depend on the model; default is the model's shortest."
},
"size": {
"type": "string",
"description": "e.g. 1280x720 (landscape) or 720x1280 (portrait). Default: the model's first size."
}
},
"required": [
"prompt"
]
}
get_video
وضعیت ساخت ویدیو و، پس از پایان، نشانی دانلود فایل MP4؛ بدون هزینه.
توضیحی که برنامه به مدل نشان میدهد:
Check a render started with create_video. When status is "completed" the answer includes the download address (GET /api/v1/videos/{id}/content); downloading it needs the same Gisoo key in the Authorization header. A failed render is refunded automatically. Free: costs nothing.
وضعیت ساخت ویدیو را میگوید و پس از پایان، نشانی دانلود فایل را میدهد؛ این ابزار هزینه ندارد.
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The job id from create_video (vid_…)."
}
},
"required": [
"id"
]
}
account_balance
موجودی اعتبار، مصرف همین کلید و سقف هزینهاش؛ بدون هزینه.
توضیحی که برنامه به مدل نشان میدهد:
Show the Gisoo AI credit balance (USD), what this key has spent, its spend limit and rate limits. Free: costs nothing.
موجودی اعتبار هوش مصنوعی، مصرف این کلید و سقفهای آن؛ این ابزار هزینه ندارد.
ورودی ندارد.
{
"type": "object",
"properties": {}
}
شکل پاسخ
پاسخ هر ابزار یک بلوک text دارد که مدل اول میخواند و برای ابزارهای پولی، خط آخرش مدل، توکنها، هزینه به دلار و شناسهٔ درخواست است.
تصویر به شکل بلوک image و گفتار و موسیقی به شکل بلوک audio (base64 با mimeType) میآیند. خلاصهٔ ماشینی در structuredContent است:
request_id و cost_usd برای ابزارهای پولی.
برای سرورها و کاربران داخل ایران، در این نمونه نشانی gisoo.pro را با ir.gisoo.pro جایگزین کنید؛ مسیر و کلید هماناند.
curl https://gisoo.pro/api/mcp \
-H "Authorization: Bearer $GISOO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call",
"params": {"name": "ask_model", "arguments": {"model": "gemini-3.6-flash", "prompt": "In one line: what is MCP?"}}}'
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"content": [
{ "type": "text", "text": "MCP is an open protocol that lets AI apps call outside tools…\n\n[model gemini-3.6-flash · 21 input / 18 output tokens · cost $… (charged from Gisoo credit) · request req_…]" }
],
"isError": false,
"structuredContent": { "model": "gemini-3.6-flash", "finish_reason": "stop", "usage": { "prompt_tokens": 21, "completion_tokens": 18, "total_tokens": 39 }, "request_id": "req_…", "cost_usd": "…" }
}
}
با GET /api/v1/requests/{id} و همان کلید، وضعیت و هزینهٔ هر درخواست را دوباره میخوانید.
ویدیو: کار، نه فایل
create_video کار را شروع میکند و شناسهٔ vid_… را برمیگرداند. هزینه همان لحظه که سرویسدهنده کار را میپذیرد کم میشود و اگر ساخت ناموفق باشد کامل برمیگردد.
get_video وضعیت را میگوید و وقتی completed شد، نشانی https://gisoo.pro/api/v1/videos/{id}/content را میدهد. فایل را با همان کلید در سربرگ Authorization بگیرید
(جزئیات در ساخت ویدیو). ویدیو فقط برای پروژهٔ همان کلید دیده میشود.
تنظیم برنامهها
در همهٔ نمونهها بهجای sk-gisoo-v1-... کلید خودتان را بگذارید.
Claude Code
در ترمینال، یک بار این دستور را بزنید:
برای سرورها و کاربران داخل ایران، در این نمونه نشانی gisoo.pro را با ir.gisoo.pro جایگزین کنید؛ مسیر و کلید هماناند.
claude mcp add --transport http --scope user gisoo https://gisoo.pro/api/mcp \
--header "Authorization: Bearer sk-gisoo-v1-..."
با --scope user سرور در همهٔ پروژهها در دسترس است. برای دیدن وضعیت، داخل Claude Code دستور /mcp را بزنید.
Cursor
فایل ~/.cursor/mcp.json (برای همهٔ پروژهها) یا .cursor/mcp.json در پوشهٔ پروژه:
برای سرورها و کاربران داخل ایران، در این نمونه نشانی gisoo.pro را با ir.gisoo.pro جایگزین کنید؛ مسیر و کلید هماناند.
{
"mcpServers": {
"gisoo": {
"url": "https://gisoo.pro/api/mcp",
"headers": { "Authorization": "Bearer sk-gisoo-v1-..." }
}
}
}
بعد از ذخیره، در Settings بخش MCP سرور gisoo باید سبز شود و فهرست ابزارهایش را نشان بدهد.
VS Code (Copilot)
فایل .vscode/mcp.json در پروژه، یا از Command Palette فرمان MCP: Open User Configuration:
برای سرورها و کاربران داخل ایران، در این نمونه نشانی gisoo.pro را با ir.gisoo.pro جایگزین کنید؛ مسیر و کلید هماناند.
{
"inputs": [
{ "type": "promptString", "id": "gisoo-key", "description": "Gisoo API key", "password": true }
],
"servers": {
"gisoo": {
"type": "http",
"url": "https://gisoo.pro/api/mcp",
"headers": { "Authorization": "Bearer ${input:gisoo-key}" }
}
}
}
VS Code کلید را بار اول از شما میپرسد و جای امنی نگه میدارد، پس در فایل پروژه نمینشیند. ابزارها در حالت Agent گفتوگوی Copilot دیده میشوند.
Cline
در Cline، بخش MCP Servers، گزینهٔ Configure MCP Servers فایل cline_mcp_settings.json را باز میکند:
برای سرورها و کاربران داخل ایران، در این نمونه نشانی gisoo.pro را با ir.gisoo.pro جایگزین کنید؛ مسیر و کلید هماناند.
{
"mcpServers": {
"gisoo": {
"type": "streamableHttp",
"url": "https://gisoo.pro/api/mcp",
"headers": { "Authorization": "Bearer sk-gisoo-v1-..." },
"disabled": false
}
}
}
Cline پیش از هر فراخوانی ابزار اجازه میگیرد؛ ابزارهای پولی را در فهرست autoApprove نگذارید.
Claude Desktop
در Settings، بخش Developer، دکمهٔ Edit Config فایل claude_desktop_config.json را باز میکند:
برای سرورها و کاربران داخل ایران، در این نمونه نشانی gisoo.pro را با ir.gisoo.pro جایگزین کنید؛ مسیر و کلید هماناند.
{
"mcpServers": {
"gisoo": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://gisoo.pro/api/mcp", "--header", "Authorization:${GISOO_AUTH}", "--transport", "http-only"],
"env": { "GISOO_AUTH": "Bearer sk-gisoo-v1-..." }
}
}
}
این فایل فقط برنامههای روی دستگاه خودتان را اجرا میکند، پس برنامهٔ کوچک mcp-remote پل اتصال به گیسو میشود و Node.js نسخهٔ ۱۸ یا بالاتر لازم دارد. بعد از ذخیره، Claude Desktop را کامل ببندید و دوباره باز کنید.
هزینه
- اتصال،
initialize،tools/listو ابزارهای رایگان (list_models،get_video،account_balance) هزینه ندارند. - ابزارهای پولی دقیقاً مثل endpoint معادلشان قیمت میخورند: پیش از اجرا مبلغی کنار گذاشته میشود و بعد فقط هزینهٔ واقعی کم میشود (صورتحساب).
- سقف هزینهٔ کلید، بودجهٔ ماهانهٔ پروژه، فهرست مدلهای مجاز و سقف مصرف پیش از احراز هویت همینجا هم اعمال میشوند.
خطاها
پیش از JSON-RPC، همان خطاهای HTTP وبسرویس در قالب OpenAI برمیگردند:
| وضعیت | error.code | معنا |
|---|---|---|
| ۴۰۱ | missing_api_key، invalid_api_key، api_key_revoked، api_key_expired | کلید نیامده یا معتبر نیست. پاسخ سربرگ WWW-Authenticate: Bearer دارد. |
| ۴۰۳ | ip_not_allowed | IP شما در فهرست مجاز کلید نیست. |
| ۴۱۳ | request_too_large | بدنهٔ درخواست از سقف بزرگتر است. |
| ۴۲۹ | rate_limit_exceeded | سقف درخواست در دقیقهٔ کلید پر شده؛ با سربرگ Retry-After. |
| ۵۰۳ | gateway_disabled | وبسرویس موقتاً خاموش است. |
خطای پروتکل در error پاسخ JSON-RPC میآید: -32700 بدنهٔ نامعتبر، -32600 پیام نامعتبر یا دستهٔ بیش از ۱۰ پیام، -32601 روش ناشناخته، -32603 خطای داخلی.
خطای ابزار پاسخ عادی است با isError: true، تا مدل بخواند و راه دیگری برود. متن، پیام فارسی خود وبسرویس است و کد آن در structuredContent.error
(مثل insufficient_credit، key_spend_limit_reached، model_not_allowed، kyc_required، model_not_found، model_endpoint_mismatch؛ فهرست کامل در خطاها).
کدهای مخصوص MCP: unknown_tool، one_call_per_request، video_not_found. ابزاری که خطا بدهد هزینه ندارد.
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [{ "type": "text", "text": "اعتبار کافی نیست. … [insufficient_credit]" }],
"structuredContent": { "error": "insufficient_credit", "message": "اعتبار کافی نیست. … [insufficient_credit]" },
"isError": true
}
}
محدودیتها
- هر
POSTیک درخواست از سقف دقیقهای کلید است (۶۰ بهطور پیشفرض)، حتیinitializeوtools/list. - هر درخواست HTTP حداکثر یک
tools/callاجرا میکند؛ در یک دسته، فراخوانی دوم خطایone_call_per_requestمیگیرد. - هر درخواست حداکثر ۱۰۰ ثانیه فرصت دارد. برای همین
ask_modelبهطور پیشفرضmax_tokensبرابر ۲۰۴۸ دارد (حداکثر ۸۱۹۲) و ویدیو کار جداگانه است. text_to_speechحداکثر ۲۰۰۰ نویسه میگیرد؛ متن بلندتر را در چند بخش بفرستید.- تبدیل فایل صوتی به متن، امبدینگ و ورودی تصویر در MCP نیستند؛ از endpointهای خود وبسرویس استفاده کنید.
پاسخ پرسشتان را پیدا نکردید؟
شناسهٔ درخواست (هدر X-Request-Id) را با پرسشتان در تیکت بفرستید تا دقیق بررسی کنیم.