← Blog developer

Pay by Square cez MCP — AI agenti generujú QR kódy

Easy Square MCP server umožňuje Claude, Cursor a ďalším AI nástrojom generovať Pay by Square QR kódy automaticky.

Úvod

Model Context Protocol (MCP) je otvorený štandard, ktorý umožňuje AI agentom volať externé nástroje priamo v konverzácii. Easy Square exponuje MCP server — to znamená, že Claude, Cursor, Windsurf a vlastní AI agenti môžu generovať Pay by Square QR kódy bez písania akéhokoľvek kódu. Používateľ napíše "Vygeneruj QR kód pre platbu 42,50 € na účet SK31...", AI zavolá Easy Square a vráti obrázok.

Tento článok vysvetlí ako MCP funguje, ukáže konfiguráciu pre Claude Desktop, a na konci nájdete kompletný Node.js test klient zabalený v Dockeri — overíte tak, že MCP server funguje, ešte pred nasadením do AI nástroja.

Čo je MCP v skratke

MCP rieši problém, že AI modely nemajú prístup k vonkajšiemu svetu. Model vie generovať text, ale neumie zavolať API, prečítať súbor alebo zapisovať do databázy. MCP server stojí medzi AI agentom a externou službou — agent pošle požiadavku podľa JSON-RPC 2.0 protokolu a server ju preloží do reálneho API volania.

Výhoda pre Easy Square: raz napísaný MCP server obsluhuje všetky AI nástroje, ktoré MCP podporujú. Nemusíte mať samostatný plugin pre Claude, samostatný pre Cursor a samostatný pre n8n — jeden MCP endpoint stačí pre všetkých.

Viac o protokole nájdete na modelcontextprotocol.io.

Kde to použiť — tri príklady

Claude Desktop

Po konfigurácii MCP servera môžete v Claude Desktop napísať: "Vygeneruj QR kód pre faktúru 2026001, suma 150 €, účet SK31 1200 0000 1987 4263 7541". Claude zavolá Easy Square, dostane PNG a zobrazí ho priamo v konverzácii. Hodí sa pre účtovníkov a freelancerov, ktorí denne posielajú niekoľko faktúr.

Cursor / Windsurf (AI IDE)

Pri písaní fakturačného kódu sa Cursor spýta: "Chceš, aby som vygeneroval testovací QR kód pre overenie integrácie?" IDE zavolá MCP server a vloží PNG priamo do testu. Skráti to vývojový cyklus pre každého, kto pracuje na Pay by Square integráciách.

Vlastný AI agent (n8n, LangChain, custom)

Automatizačné pipeline — napríklad n8n workflow, ktorý sleduje nové záznamy vo vašom fakturačnom systéme a generuje pre ne QR kódy — môžu volať MCP server rovnako ako akýkoľvek iný nástroj. Kód agenta pozostáva z niekoľkých riadkov, ktoré vyvolajú tools/call s menom generate_qr.

Konfigurácia pre Claude Desktop

V Claude Desktop otvorte claude_desktop_config.json (Settings → Developer → Edit Config) a pridajte:

{
  "mcpServers": {
    "easy-square": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.easy-square.sk/mcp",
        "--header", "X-Api-Email:vas@email.sk",
        "--header", "X-Api-Key:esq_vas_kluc"
      ]
    }
  }
}

mcp-remote je oficiálny tunel klient, ktorý preklenie rozdiel medzi stdin/stdout protokolom (ktorý Claude Desktop očakáva) a HTTP endpointom Easy Square MCP servera.

Reštartujte Claude Desktop — v pravom dolnom rohu by ste mali vidieť ikonku pripojeného MCP servera. V konverzácii napíšte "Vygeneruj Pay by Square QR kód..." a Claude automaticky zavolá tool generate_qr.

Test klient v Node.js — Docker

Ak si chcete overiť, že MCP server funguje ešte pred nastavením Claude Desktop, spustite nižšie uvedený Node.js klient v Dockeri. Urobí tri JSON-RPC volania — initialize, tools/list a tools/call — a uloží vygenerovaný PNG.

client.mjs

import { writeFile } from 'node:fs/promises';

const endpoint = 'https://mcp.easy-square.sk/mcp';
const apiEmail = process.env.ES_API_EMAIL;
const apiKey = process.env.ES_API_KEY;

async function mcp(method, params) {
  const res = await fetch(endpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'application/json, text/event-stream',
      'X-Api-Email': apiEmail,
      'X-Api-Key': apiKey,
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: Math.floor(Math.random() * 1e9),
      method,
      ...(params && { params }),
    }),
  });

  const text = await res.text();
  const json = text.startsWith('event:') || text.startsWith('data:')
    ? JSON.parse(text.split('\n').find(l => l.startsWith('data: ')).slice(6))
    : JSON.parse(text);
  if (json.error) throw new Error(`${json.error.code}: ${json.error.message}`);
  return json;
}

// 1. Initialize
const init = await mcp('initialize', {
  protocolVersion: '2024-11-05',
  clientInfo: { name: 'test-client', version: '1.0.0' },
  capabilities: {},
});
console.log('Server:', init.result.serverInfo.name);

// 2. List tools
const tools = await mcp('tools/list');
console.log('Tools:', tools.result.tools.map(t => t.name).join(', '));

// 3. Call generate_qr
const qr = await mcp('tools/call', {
  name: 'generate_qr',
  arguments: {
    iban: 'SK3112000000198742637541',
    amount: 42.50,
    beneficiary_name: 'Firma s.r.o.',
    variable_symbol: '2026001',
  },
});

const image = qr.result.content.find(c => c.type === 'image');
const buffer = Buffer.from(image.data, 'base64');
await writeFile('qr.png', buffer);
console.log(`QR kód uložený: qr.png (${buffer.length} bajtov)`);

Dockerfile

FROM node:20-alpine
WORKDIR /app
COPY client.mjs .
CMD ["node", "client.mjs"]

Spustenie

docker build -t es-mcp .
docker run --rm \
  -e ES_API_EMAIL=vas@email.sk \
  -e ES_API_KEY=esq_vas_kluc \
  -v $(pwd):/app/out \
  es-mcp

Upravte cestu v writeFile na /app/out/qr.png, aby súbor skončil v aktuálnom priečinku. Výstup ukáže meno servera, zoznam toolov a potvrdí vygenerovaný QR kód.

Príklad konverzácie s AI agentom

Po správnej konfigurácii vyzerá interakcia s Claude Desktop asi takto:

Vy: Vygeneruj platobný QR kód pre faktúru číslo 2026001. Príjemca Ondrúš Software s.r.o., účet SK31 1200 0000 1987 4263 7541, suma 150 €.

Claude: Vygenerujem QR kód pomocou Easy Square MCP...

(Claude zavolá tool generate_qr s parametrami, server vráti PNG)

Claude: Tu je vygenerovaný QR kód:

(inline PNG obrázok)

Kód obsahuje všetky platobné údaje. Platnosť URL je 24 hodín, ale samotný obrázok sa neprehrá ani neskôr — len nebude dostupný ako download link.

Technické detaily

Easy Square MCP server beží na HTTPS endpointe https://mcp.easy-square.sk/mcp. Podporuje dva transporty — Streamable HTTP (stateless POST/response) a SSE (persistent session). Pre jednoduché integrácie odporúčame Streamable HTTP — je stateless, žiadne session UUID, autentifikácia na každom requeste.

Parametre tool generate_qr používajú snake_case (na rozdiel od REST API, ktoré používa camelCase). Povinné parametre sú iban a amount, ostatné majú rozumné defaulty. Response obsahuje dve content položky — text metadata s qr_code_url (24h expiry) a image s PNG ako base64.

Rate limit na MCP server je 1000 volaní za hodinu na API kľúč. Pre zvýšenie kontaktujte podporu.

Záver

MCP premieňa Easy Square na nástroj dostupný pre ľubovoľného AI agenta. Raz nakonfigurovaný server obsluhuje Claude, Cursor, Windsurf aj vlastné pipeline. Pre developerov to znamená menej manuálnej práce pri testovaní, pre koncových používateľov prirodzenú cestu k platobným QR kódom cez AI konverzáciu.

Kompletnú dokumentáciu MCP servera, vrátane všetkých parametrov tool generate_qr a SSE variantu, nájdete na dokumentacia-mcp. API kľúč pre prístup k MCP získate po registrácii na easy-square.sk/registracia/. REST API variant pre projekty bez AI nájdete v článku Pay by Square QR kód v Node.js cez REST API.