MCP-сервер

Пошаговое подключение клиентов (Claude Code, Claude Desktop, Cursor, VS Code) — «Подключение через MCP». Здесь — полный справочник: адрес, авторизация и все восемь инструментов с их параметрами.

Адрес и авторизацияСкопировать ссылку

• Адрес сервера — https://api.typizer.ru/mcp (только POST; GET и DELETE отвечают 405: сессий и потока событий у этого сервера нет — каждый вызов самостоятельный).
• Авторизация — только ключ API в заголовке Authorization: Bearer tz_live_… (тот же ключ и те же скоупы, что у REST API — см. «Ключи API»). Сессия кабинета для MCP не принимается.
• Отсутствующий или неверный ключ — 401 с WWW-Authenticate: Bearer realm="typizer" (error="invalid_token" для просроченного/отозванного ключа, error="invalid_request" для неверного заголовка).
• OAuth не используется. У /mcp нет /.well-known/oauth-protected-resource (запрос на этот путь — обычный 404, ресурс не объявлен) — протокол авторизации MCP требует, чтобы этот документ называл хотя бы один сервер авторизации, а в v1 его нет: единственный способ войти — ключ API. OAuth 2.1 для MCP — в планах, не реализован.
• Файлы в инструментах (file_base64, sample_base64) передаются как base64 внутри тела JSON-RPC, размером не больше 50 МБ (MAX_FILE_BYTES) — столько же, сколько и в REST API.

ИнструментыСкопировать ссылку

Каждый вызов проверяет тот же скоуп, что REST API потребовал бы для аналогичного действия — ключ без нужного скоупа получает insufficient_scope, как и в REST.

? — необязательный параметр. Создание и обновление типизатора, а также extract, работают так же, как соответствующий маршрут REST API: extract резервирует страницы с баланса и списывает их при завершении, create_typizer расходует дневную квоту ИИ-ассистента — те же числа, что у POST /v1/typizers/generate («Лимиты»).

extractСкопировать ссылку

Главный инструмент: извлекает данные из документа по сохранённому типизатору или разовой схеме.

idempotency_key работает как заголовок Idempotency-Key REST API («Обработка ошибок и повторов»): тот же ключ с теми же аргументами в течение 24 часов возвращает тот же прогон вместо создания (и повторной оплаты) нового; тот же ключ с другими аргументами — ошибка. У MCP нет HTTP-заголовков, поэтому этот аргумент — единственный способ сделать повтор extract безопасным; без него каждый вызов создаёт новый прогон.

Пример аргументов и результата:

// Аргументы вызова extract
{
  "typizer_id": "tz_01J…",
  "file_url": "https://typizer.ru/samples/invoice.pdf",
  "wait_seconds": 50,
  "idempotency_key": "agent-run-2026-10-31-0007"
}

// Результат — тот же объект Run, что и REST API (см. «Форматы результата»),
// отдаётся агенту и как structuredContent, и как текст JSON
{
  "id": "run_01J…",
  "status": "succeeded",
  "format": "json",
  "pages": { "physical": 1, "billed": 1 },
  "output": { "invoice_number": "A-204", "total": 15000 },
  "fields": { "total": { "status": "ok", "sources": [] } }
}

При ошибке (например, недостаточно баланса или типизатор не найден) результат инструмента помечается isError, а текстом идёт то же тело проблемы, что вернул бы REST API (для 402 — без ссылки, с тем же нейтральным текстом «недостаточно страниц на балансе»).

ПроверкаСкопировать ссылку

После подключения спросите агента «Какие типизаторы у меня есть?» — это вызовет list_typizers. Логи сервера хранят имя инструмента, идентификаторы и коды ошибок — никогда аргументы, имена файлов или результат.

КлиентыСкопировать ссылку

Подробная настройка каждого клиента, с пояснениями — «Подключение через MCP». Конфигурация в двух словах:

Claude Code — нативная поддержка заголовка авторизации:

claude mcp add --transport http typizer https://api.typizer.ru/mcp --header "Authorization: Bearer tz_live_…"

Claude Desktop — через мост mcp-remote (его удалённые коннекторы не передают свой заголовок Authorization; схема может измениться в новой версии клиента — см. тьюториал):

{
  "mcpServers": {
    "typizer": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.typizer.ru/mcp",
        "--header",
        "Authorization:${TYPIZER_AUTH}"
      ],
      "env": {
        "TYPIZER_AUTH": "Bearer tz_live_…"
      }
    }
  }
}

Cursor — нативная поддержка удалённых HTTP-серверов с заголовками (по документации Cursor на момент написания):

{
  "mcpServers": {
    "typizer": {
      "url": "https://api.typizer.ru/mcp",
      "headers": {
        "Authorization": "Bearer tz_live_…"
      }
    }
  }
}

VS Code — нативная поддержка удалённых HTTP-серверов с заголовками (по документации VS Code на момент написания):

{
  "servers": {
    "typizer": {
      "type": "http",
      "url": "https://api.typizer.ru/mcp",
      "headers": {
        "Authorization": "Bearer tz_live_…"
      }
    }
  }
}

Что дальшеСкопировать ссылку

• «Подключение через MCP» — пошаговая настройка каждого клиента.
• «Ключи API» — скоупы и как завести отдельный ключ для агента.
• «Обработка ошибок и повторов» — коды ошибок и идемпотентность.