Стройте на метафорических картах

Выберите путь

Три способа поговорить с нашим API. Выберите, что подходит под ваш сценарий, и переходите в нужную доку.

OAuth: подключение в один клик из ChatGPT и Claude

Если ваши пользователи начинают из ChatGPT или Claude, копировать API-ключ не нужно. Чат показывает нашу страницу согласия, пользователь нажимает «Разрешить», и чат получает токен с ограниченным набором действий. Отозвать доступ можно из профиля в любой момент.

Что можно строить уже сейчас

REST quick-start

Две команды: тянем карту, забираем картинку. Без вебхуков, без коллбеков, без preflight.

KEY=mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 1) Тянем карту из любой доступной колоды
curl -X POST https://app.makcards.online/api/v1/public/draw \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope":"any","count":1,"image_width":1024}'

# 2) В ответе есть drawn[0].image_url – забираем как есть
curl https://app.makcards.online/api/v1/public/decks/.../cards/.../image?w=1024&token=eyJhbGc... \
  -o card.jpg

Полная машиночитаемая спека: openapi.json · ИИ-совместимый сабсет: openapi.ai.json · Гайд для пользователей: docs/ru/24-public-api.

Получите API-ключ

1. 1
   Войдите в приложение.

   Откройте app.makcards.online и войдите через Google или Yandex. Один клик, отдельной регистрации не нужно.

2. 2
   Откройте «Профиль → Доступ для ИИ и интеграций».

   Раздел рядом с Premium и Достижениями. То же место, где магазины берут свой ключ.

3. 3
   Сгенерируйте ключ и сразу скопируйте.

   Ключ выглядит как mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx. Показывается один раз; второго раза не будет. Сохраните в менеджер паролей или ваше секретное хранилище.

4. 4
   Относитесь к ключу как к паролю.

   Никаких публичных репозиториев, чатов поддержки, скриншотов. Если ключ мог утечь – перегенерируйте: старый перестанет работать в течение минуты.

Подключение по API-ключу

Один ключ, семь поверхностей. Hosted MCP – быстрый старт, local stdio оставляет ключ на машине, обычный Bash – для агентов, у которых уже есть shell. Выберите по своему клиенту.

{
  "mcpServers": {
    "makcards": {
      "type": "http",
      "url": "https://mcp.makcards.online/v1",
      "headers": {
        "Authorization": "Bearer mk_live_xxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

{
  "mcpServers": {
    "makcards": {
      "type": "http",
      "url": "https://mcp.makcards.online/v1",
      "headers": {
        "Authorization": "Bearer mk_live_xxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

URL:      https://app.makcards.online/api/v1/public/draw
Method:   POST
Headers:  Authorization: Bearer mk_live_xxxxxxxxxxxxxxxxxx
          Content-Type: application/json
Body:     { "scope": "any", "count": 1, "image_width": 1024 }

Action source: https://makcards.online/api/v1/public/openapi.ai.json
Authentication: API Key (Bearer)
Auth value:     mk_live_xxxxxxxxxxxxxxxxxx

{
  "mcpServers": {
    "makcards": {
      "command": "npx",
      "args": ["-y", "@maccards/mcp"],
      "env": {
        "MAKCARDS_API_KEY": "mk_live_xxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

{
  "mcpServers": {
    "makcards": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "MAKCARDS_API_KEY",
        "ghcr.io/makcards/mcp:latest",
        "node", "dist/transports/stdio.js"
      ],
      "env": {
        "MAKCARDS_API_KEY": "mk_live_xxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

{
  "mcpServers": {
    "makcards": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--platform", "linux/amd64",
        "-e", "MAKCARDS_API_KEY",
        "ghcr.io/makcards/mcp:latest",
        "node", "dist/transports/stdio.js"
      ],
      "env": {
        "MAKCARDS_API_KEY": "mk_live_xxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

# Один раз: переменные окружения
export MAKCARDS_API_KEY=mk_live_xxxxxxxxxxxxxxxxxx
BASE=https://app.makcards.online/api/v1/public
H="Authorization: Bearer $MAKCARDS_API_KEY"

# Список колод, доступных по ключу
curl -s -H "$H" "$BASE/decks" | jq

# Тянем 3 карты из любой доступной колоды
curl -s -X POST "$BASE/draw" -H "$H" -H "Content-Type: application/json" \
  -d '{"scope":"any","count":3,"image_width":1024}' | jq

# Сохраняем первую картинку сразу на диск
curl -s -X POST "$BASE/draw" -H "$H" -H "Content-Type: application/json" \
  -d '{"scope":"any","count":1,"image_width":1024}' \
  | jq -r '.drawn[0].image_url' \
  | xargs curl -s -o card.jpg

# Состояние rate-limit'ов
curl -s -H "$H" "$BASE/usage" | jq

Hosted, local или shell? Hosted MCP (mcp.makcards.online) – самый быстрый путь, проходит через корпоративные прокси. Local stdio – когда security-политика говорит «никаких сторонних MCP-сервисов»: ИИ-клиент общается с локальным процессом, а тот уже идёт в наш REST с вашим ключом. Bash полностью пропускает MCP-слой и подходит только агентам, которые уже умеют shell. Те же tools, те же данные.

Скилл агента: makcards-self-reflection

Подключить источник карт – половина настройки. Вторая половина – поведение: как агент ведёт сессию рефлексии. Скилл makcards-self-reflection и есть эта половина. Он работает с любым агентом, у которого есть источник карт, не только с Claude.

Три техники

Получить скилл

Два способа, содержимое одно. ZIP проще всего; публичный репо удобен, если вы предпочитаете git или хотите следить за обновлениями. Подходит любому агенту.

git clone https://github.com/makcards/skills

Подключить под ваш агент

На каждый агент две части: источник карт (вкладки Connect выше) и место, где живёт поведение. У Claude это SKILL.md; у остальных – references/agent-instructions.md, вставленный в системный промпт. Source of truth один файл, поэтому поведение везде одинаковое.

Впервые сталкиваетесь с метафорическими картами или вы не разработчик? Разбор простым языком проведёт от нуля до первой сессии.

Лимиты запросов

На аккаунт, по окнам. POST /draw с count=N считается как N запросов в счётчик карт.

Текущее состояние – GET /api/v1/public/usage. На каждом ответе заголовки RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (RFC 9331).

Приватность и безопасность

Подробнее: Условия использования · Политика конфиденциальности.

FAQ

Частые вопросы интеграторов.