MCP (Model Context Protocol)

Если вам нужно интегрировать вашего агента, то передайте ему эту документацию .

JSON-RPC 2.0-эндпоинт, позволяющий подключить внешние ИИ-агенты к сервису через Model Context Protocol. Подходит для сторонних MCP-клиентов, плагинов редакторов кода, CLI и любых инструментов, поддерживающих tools/call.

Эндпоинт

POSThttps://ai.wormsoft.ru/api/mcp

• POST — JSON-RPC 2.0 диспетчер (единственный поддерживаемый метод).
• GET и DELETE — вернут 405 Method Not Allowed.
• Авторизация — тот же стек, что и у REST: API-ключ или Bearer-токен (JWT агента).
• Доступен только на платных подписках (FREE не поддерживается).

Привязка агента к аккаунту

Каждый MCP-запрос привязан к пользователю через Authorization. В зависимости от клиента это может быть:

• API-ключ — Authorization: Bearer YOUR_API_KEY.
• JWT агента — Authorization: Bearer <agent-jwt>, если ваш агент аутентифицирован в нашей системе.

Токен определяет, под каким аккаунтом выполняются инструменты, и списываются с баланса. Не передавайте один и тот же ключ нескольким доверенным агентам.

Доступные инструменты

Список инструментов можно получить запросом tools/list. Ниже описаны три доступных инструмента.

web_search

Поиск в интернете по запросу.

{
  "query": "string (обязательно)",
  "max_results": "число 1-10 (необязательно)"
}

web_fetch

Загрузка содержимого веб-страницы по URL.

{
  "url": "string (обязательно)"
}

recognize_image_content

Распознавание текста на изображении и в PDF-документах (OCR). Модель возвращает данные строго по переданной JSON-Schema (tool-calling).

{
  "sources": [
    { "image": "data:image/png;base64,..." },
        { "pdfFile": "`base64 код PDF-файла` }
  ],
  "prompt": "string (необязательно)",
  "responseSchema": { "type": "object", ... },
  "model": "wormsoft/vision/medium"
}

• sources — массив источников; в каждом элементе ровно один из image / pdfFile (base64).
• prompt — уточняющая инструкция, добавляется в общий запрос к модели.
• responseSchema — JSON Schema ответа (передается в tool-calling).
• model — vision-модель провайдера с поддержкой tool-calling.
• Ограничения: до 20 источников за запрос, размер одного источника до 25 МБ.

Пример подключения

Отправьте JSON-RPC-запрос методом tools/call:

curl -X POST https://ai.wormsoft.ru/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "web_search",
      "arguments": { "query": "NestJS", "max_results": 5 }
    }
  }'

Формат ответа

Успешный вызов инструмента возвращает результат в result.content. Текст инструментов оформлен как JSON для удобства парсинга.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "{\n  \"model\": \"wormsoft/vision/medium\",\n   \"documents\": [...],\n   \"usage\": { \"credits\": 100 }\n}" }
    ]
  }
}

Протокол JSON-RPC 2.0

• Одноточечный запрос → один объект ответа.
• Пакет запросов (массив) → массив объектов ответов.
• Уведомление (без id) → 202 с пустым телом.
• Поддерживаемые методы: initialize, ping, tools/list, tools/call.

Ошибки

Code	Описание
-32600	Invalid Request — повреждённый JSON-RPC-запрос.
-32601	Method not found — неизвестный метод.
-32602	Invalid params — неверные параметры инструмента.
-32000	Server error — unsupported метод (GET/DELETE → 405).
-32603	Internal error — ошибка на стороне сервера (например, превышен лимит).

Ошибки выполнения инструмента (например, неверный query или недоступный url, неверный sources или недостижимый image/pdfFile) возвращаются в result.isError: true с текстом сообщения.

Тарификация

• web_search — списание кредитов пропорционально количеству результатов.
• web_fetch — фиксированные 2000 кредитов за запрос.
• recognize_image_content — распознавание по токенам (как операция ocr): 1 кредит за 1K входных токенов и 4000 кредитов за 1K выходных.
• Списание происходит только при успешном ответе инструмента.
• Кредиты списываются с буста и лимита подписки; при нехватке остаток уходит в долг.

Доступность

Эндпоинт доступен только пользователям с платной подпиской. На тарифе FREE запрос вернёт 403 Forbidden — обновите подписку, чтобы получить доступ к MCP.