Build with metaphor cards

Pick a path

Three ways agents talk to us. Pick the one that matches what you are building, then jump to the right doc.

OAuth: one-click connect from ChatGPT and Claude

If your users start from ChatGPT or Claude, they don’t need to copy an API key. The chat app shows our consent screen, the user clicks Allow, and the chat gets a scoped token. The user can revoke access from their Profile any time.

What you can build today

REST quick-start

Two commands: draw a card, fetch its image. No webhook, no callback, no pre-flight.

KEY=mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 1) Draw one card from any accessible deck
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) Response carries drawn[0].image_url – fetch it as-is
curl https://app.makcards.online/api/v1/public/decks/.../cards/.../image?w=1024&token=eyJhbGc... \
  -o card.jpg

Full machine-readable reference: openapi.json · AI-safe subset: openapi.ai.json · User guide: docs/en/24-public-api.

Get an API key

1. 1
   Sign in to the app.

   Open app.makcards.online and sign in (Google or Yandex). One click, no separate account.

2. 2
   Open Profile → Access for AI and integrations.

   The section sits next to Premium and Achievements. Same place shop partners use.

3. 3
   Generate the key and copy it.

   The key looks like mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx. It is shown once; the second view never happens. Paste it into a password manager or your secret store.

4. 4
   Treat the key as a password.

   No public repositories, no support chats, no screenshots. If a key may have leaked, regenerate it – the old one stops working within a minute.

Connect with API key

Same key, seven surfaces. Hosted MCP for fast setup, local stdio to keep the key on your machine, plain Bash for agents that already have a shell. Pick what matches your client.

{
  "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"
      }
    }
  }
}

# One-time setup
export MAKCARDS_API_KEY=mk_live_xxxxxxxxxxxxxxxxxx
BASE=https://app.makcards.online/api/v1/public
H="Authorization: Bearer $MAKCARDS_API_KEY"

# List decks your key can read
curl -s -H "$H" "$BASE/decks" | jq

# Draw 3 cards from any accessible deck
curl -s -X POST "$BASE/draw" -H "$H" -H "Content-Type: application/json" \
  -d '{"scope":"any","count":3,"image_width":1024}' | jq

# Save the first card image straight to disk
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

# Inspect rate-limit state
curl -s -H "$H" "$BASE/usage" | jq

Hosted, local, or shell? Hosted MCP (mcp.makcards.online) is the fastest path and works behind corporate proxies. Local stdio is the choice when your security policy says «no third-party MCP services»: your AI client talks to a local process, which talks to our REST API with your key. Bash skips the MCP layer entirely and only fits agents that can already shell out. Same tools, same data.

Agent skill: makcards-self-reflection

Connecting a card source is half the setup. The other half is behavior: how the agent runs a reflection session. The makcards-self-reflection skill is that half. It works with any agent that has a card source, not just Claude.

Three techniques

Get the skill

Two ways, same content. The ZIP is the simplest; the public repo is handy if you prefer git or want to follow updates. It runs with any agent.

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

Set it up per agent

Two parts per agent: a card source (the connect tabs above) and where the behavior lives. For Claude that is SKILL.md; for everything else it is references/agent-instructions.md pasted into the system prompt. One file is the source of truth, so the behavior is the same everywhere.

New to metaphor cards, or not a developer? The plain-language walkthrough takes you from zero to a first session.

Rate limits

Per-account, per-window. POST /draw is batch-accounted: count=5 consumes 5 units.

Live state at GET /api/v1/public/usage. Headers on every response: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (RFC 9331).

Privacy and safety

Details: Terms of Service · Privacy Policy.

FAQ

Common questions from integrators.