MCP Dokumentácia

Čo je MCP

Model Context Protocol (MCP) je otvorený štandard pre komunikáciu medzi AI modelmi a externými nástrojmi. Easy Square MCP server umožňuje AI agentom generovať Pay by Square QR kódy priamo počas konverzácie.

Použitie: Claude Desktop, vlastné AI agenty, chatboty, automatizačné systémy.

Rýchly štart — Claude Desktop

Najjednoduchší spôsob pripojenia. Nevyžaduje Node.js ani konfiguračné súbory.

Nastavenie (3 kroky)

Otvorte Claude Desktop → Settings → Connectors
Kliknite Add custom connector
Zadajte Server URL:

https://mcp.easy-square.sk/mcp

Kliknite Save

Prihlásenie

Po uložení sa otvorí prihlasovací formulár. Zadajte:

Pole	Hodnota
Email	Váš registračný email
API kľúč	Váš API kľúč (`esq_...`)

Používate rovnaké údaje ako pre REST API. Získate ich po registrácii.

Po úspešnom prihlásení je Easy Square pripojený. Môžete písať:

"Vygeneruj QR kód na platbu 50 EUR na IBAN SK7700000000000000000000 pre firmu Firma s.r.o."

Claude automaticky zavolá generate_qr nástroj a zobrazí výsledný QR kód.

Poznámka: Príklady v dokumentácii používajú testovacie údaje (fiktívny IBAN, názov firmy). Pred nasadením do produkcie nahraďte všetky hodnoty reálnymi údajmi.

Alternatíva — mcpServers konfigurácia

Pre pokročilých používateľov alebo automatizáciu. Vyžaduje Node.js ≥ 20.18 (node --version na overenie).

Pridajte Easy Square do konfigurácie Claude Desktop. Súbor claude_desktop_config.json nájdete v:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Nahraďte vas@email.sk a esq_vas_api_kluc vašimi údajmi z registrácie.

Poznámka: Ak máte problémy s pripojením, skúste SSE transport: zmeňte URL na https://mcp.easy-square.sk/mcp/sse a pridajte "--transport", "sse-only" do args.

Autentifikácia

MCP server akceptuje tri spôsoby autentifikácie:

1. OAuth (Claude Desktop Connector) — odporúčané pre Claude Desktop:

Claude Desktop sa automaticky prihlási cez OAuth. Zadáte email + API kľúč vo formulári a server vydá prístupový token. Viď Rýchly štart.

2. X-Api-Email + X-Api-Key — pre mcpServers a vlastné integrácie:

X-Api-Email: vas@email.sk
X-Api-Key: esq_vas_api_kluc

3. Authorization: Bearer — spätná kompatibilita:

Authorization: Bearer esq_vas_api_kluc

API kľúč získate po registrácii. Server overuje:

Platnosť API kľúča
Aktívnu subskripciu
Oprávnenia pre konkrétne nástroje (mcp:generate_qr)
Rate limiting (požiadavky za minútu)

Protokol

Easy Square MCP podporuje dva transporty:

Streamable HTTP (odporúčaný)

Jednoduchý request-response cez štandardné HTTP:

POST /mcp
Content-Type: application/json

→ JSON-RPC request
← JSON-RPC response

Žiadne persistent connection, žiadny session management. Každý request je nezávislý.

SSE (Server-Sent Events)

Starší transport s persistent connection:

1. Klient → GET /mcp/sse
2. Server → SSE event "endpoint" s URL pre správy
3. Klient → POST /mcp/messages?sessionId=<uuid>
4. Server → SSE event "message" s JSON-RPC odpoveďou

Inicializácia session

Po pripojení k SSE streamu pošlite initialize:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "clientInfo": {
      "name": "my-app",
      "version": "1.0.0"
    }
  }
}

Odpoveď:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "serverInfo": {
      "name": "easy-square",
      "version": "1.0.0"
    },
    "capabilities": {
      "tools": { "listChanged": false }
    }
  }
}

Potom pošlite notifikáciu notifications/initialized:

{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}

Dostupné nástroje

`generate_qr`

Generuje Pay by Square QR kód. Výpis nástrojov cez tools/list:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Parametre

Parameter	Typ	Povinný	Popis
`iban`	string	áno	IBAN príjemcu (SK/CZ formát, 24 znakov)
`amount`	number	áno	Suma (0.01 – 999 999 999.99)
`currency`	string	nie	Mena: `EUR`, `CZK`, `USD` (predvolená `EUR`)
`beneficiary_name`	string	nie	Meno príjemcu (max 70 znakov)
`variable_symbol`	string	nie	Variabilný symbol (max 10 číslic)
`constant_symbol`	string	nie	Konštantný symbol (max 4 číslice)
`specific_symbol`	string	nie	Špecifický symbol (max 10 číslic)
`note`	string	nie	Správa pre príjemcu (max 140 znakov)
`due_date`	string	nie	Dátum splatnosti (YYYY-MM-DD)
`size`	integer	nie	Veľkosť v px (64–960, krok 64, predvolená 256)
`type`	string	nie	`PAY` (modrý) alebo `INVOICE` (oranžový)
`position`	string	nie	Pozícia loga: `TOP`, `BOTTOM`, `LEFT`, `RIGHT`
`color_scheme`	string	nie	Schéma: `LIGHT`, `MEDIUM`, `GRAY`, `DARK`
`with_frame`	boolean	nie	Rámik s logom (predvolená `true`)
`output_format`	string	nie	Formát: `PNG` alebo `JPEG`

Pozor: MCP používa snake_case (napr. variable_symbol), na rozdiel od REST API ktoré používa camelCase (variableSymbol).

Volanie nástroja

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "generate_qr",
    "arguments": {
      "iban": "SK7700000000000000000000",
      "amount": 50.00,
      "beneficiary_name": "Firma s.r.o.",
      "variable_symbol": "2024001"
    }
  }
}

Odpoveď

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"qrCodeUrl\":\"https://...\",\"qrCodeBase64\":\"iVBOR...\",\"iban\":\"SK82...\",\"amount\":50.00,\"currency\":\"EUR\",\"beneficiaryName\":\"Firma s.r.o.\",\"variableSymbol\":\"2024001\",\"size\":256,\"type\":\"PAY\",\"colorScheme\":\"MEDIUM\",\"position\":\"BOTTOM\",\"withFrame\":true,\"outputFormat\":\"PNG\",\"generatedAt\":\"2026-03-16T12:00:00Z\",\"expiresAt\":\"2026-03-16T13:00:00Z\"}"
      },
      {
        "type": "image",
        "data": "<base64-PNG>",
        "mimeType": "image/png"
      }
    ],
    "isError": false
  }
}

Odpoveď obsahuje:

Text s JSON metadátami (qrCodeUrl, platobné údaje, branding parametre, generatedAt/expiresAt)
Obrázok v base64 kódovaní (priamo zobraziteľný v AI klientovi)

Príklady integrácie

Python (MCP SDK)

from mcp import ClientSession
from mcp.client.sse import sse_client

API_KEY = "esq_vas_api_kluc"

async with sse_client(
    url="https://mcp.easy-square.sk/mcp/sse",
    headers={"Authorization": f"Bearer {API_KEY}"}
) as (read_stream, write_stream):
    async with ClientSession(read_stream, write_stream) as session:
        await session.initialize()

        result = await session.call_tool("generate_qr", {
            "iban": "SK7700000000000000000000",
            "amount": 50.00,
            "beneficiary_name": "Firma s.r.o.",
        })

        for content in result.content:
            if content.type == "image":
                # base64 PNG obrázok
                print(f"QR kód: {content.mimeType}")
            elif content.type == "text":
                # JSON metadáta
                print(content.text)

JavaScript (MCP SDK)

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

const API_KEY = "esq_vas_api_kluc";

const transport = new SSEClientTransport(
  new URL("https://mcp.easy-square.sk/mcp/sse"),
  { requestInit: { headers: { Authorization: `Bearer ${API_KEY}` } } }
);

const client = new Client({ name: "my-app", version: "1.0.0" });
await client.connect(transport);

const result = await client.callTool("generate_qr", {
  iban: "SK7700000000000000000000",
  amount: 50.0,
  beneficiary_name: "Firma s.r.o.",
});

for (const content of result.content) {
  if (content.type === "image") {
    // Uložiť PNG
    const buffer = Buffer.from(content.data, "base64");
    require("fs").writeFileSync("qr-code.png", buffer);
  }
}

Vlastný klient (raw SSE + fetch)

Poznámka: Prehliadačové EventSource API nepodporuje custom hlavičky. Na server-side (Node.js) použite knižnicu eventsource alebo fetch s ReadableStream:

const API_KEY = "esq_vas_api_kluc";
const BASE_URL = "https://mcp.easy-square.sk";

// 1. Pripojiť sa k SSE cez fetch (podporuje Authorization header)
const sseResponse = await fetch(`${BASE_URL}/mcp/sse`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

const reader = sseResponse.body.getReader();
const decoder = new TextDecoder();
let messagesUrl;

async function readSSE() {
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    const text = decoder.decode(value);

    // Parsovať SSE eventy
    for (const line of text.split("\n")) {
      if (line.startsWith("data: ") && !messagesUrl) {
        // Prvý event = endpoint URL
        messagesUrl = line.slice(6).trim();
        await initializeSession();
      } else if (line.startsWith("data: {")) {
        const response = JSON.parse(line.slice(6));
        handleResponse(response);
      }
    }
  }
}

// 2. Inicializovať session
async function initializeSession() {
  await fetch(messagesUrl, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: 1,
      method: "initialize",
      params: {
        protocolVersion: "2024-11-05",
        clientInfo: { name: "my-app", version: "1.0.0" },
      },
    }),
  });
}

function handleResponse(response) {
  if (response.id === 1) {
    // 3. Po inicializácii poslať notifications/initialized
    fetch(messagesUrl, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        jsonrpc: "2.0",
        method: "notifications/initialized",
      }),
    });

    // 4. Zavolať nástroj
    fetch(messagesUrl, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        jsonrpc: "2.0",
        id: 2,
        method: "tools/call",
        params: {
          name: "generate_qr",
          arguments: {
            iban: "SK7700000000000000000000",
            amount: 50.0,
            beneficiary_name: "Firma s.r.o.",
          },
        },
      }),
    });
  }

  if (response.id === 2) {
    // QR kód vygenerovaný
    console.log("Výsledok:", response.result);
  }
}

readSSE();

Session management

Parameter	Hodnota
Timeout	30 minút nečinnosti
Keepalive	Každých 15 sekúnd (SSE comment)
Ping	`{"jsonrpc":"2.0","id":99,"method":"ping"}` → `{"result":{}}`

Po vypršaní session sa treba pripojiť znova cez /mcp/sse.

Chybové kódy (JSON-RPC)

Kód	Popis	Kedy nastane
-32001	Neautorizovaný	Neplatný alebo expirovaný API kľúč
-32002	Neaktívna subskripcia	Subskripcia nie je aktívna
-32003	Zakázané	Chýba oprávnenie pre nástroj
-32005	Rate limit	Príliš veľa požiadaviek za minútu
-32600	Neplatný request	Chybný JSON-RPC formát
-32601	Metóda neexistuje	Neznáma JSON-RPC metóda
-32602	Neplatné parametre	Chýba IBAN, neplatná suma
-32603	Interná chyba	Chyba na strane servera

Príklad chybovej odpovede:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32602,
    "message": "Chyba: IBAN je povinny parameter."
  }
}

Príklady použitia

1. Jednoduchá platba za službu

Prompt:

Vygeneruj QR kód na platbu 49,99 EUR na účet SK3112000000198742637541 pre Jána Nováka, variabilný symbol 2026001.

Výsledok: AI zavolá generate_qr s parametrami iban, amount, beneficiary_name, variable_symbol a vráti PNG obrázok s Pay by Square QR kódom (256px, modrý PAY rámik).

2. Faktúra s dátumom splatnosti

Prompt:

Potrebujem QR kód na faktúru č. 2026015 pre ONDRÚŠ SOFTWARE s.r.o., IBAN SK9402000000003607366854, suma 150 EUR, splatnosť 15.4.2026. Chcem oranžový INVOICE štýl, veľkosť 512px.

Výsledok: AI zavolá generate_qr s parametrami vrátane type: "INVOICE", size: 512, due_date: "2026-04-15". QR kód bude mať oranžový rámik a veľkosť 512px.

3. Dobročinný dar s poznámkou

Prompt:

Vytvor QR kód pre dar 2 EUR organizácii Deťom s rakovinou na IBAN SK9402000000003607366854. Pridaj poznámku "Dar pre deti" a použi tmavú farebnú schému bez rámika.

Výsledok: AI zavolá generate_qr s color_scheme: "DARK", with_frame: false, note: "Dar pre deti". QR kód bude čierny bez dekoratívneho rámika.

Podpora

Máte otázky k MCP integrácii? Kontaktujte nás:

Email: info@easy-square.sk
Telefón: +421 950 218 974
Kontaktný formulár: easy-square.sk/kontakt/

Čo je MCP

Rýchly štart — Claude Desktop

Nastavenie (3 kroky)

Prihlásenie

Alternatíva — mcpServers konfigurácia

Autentifikácia

Protokol

Streamable HTTP (odporúčaný)

SSE (Server-Sent Events)

Inicializácia session

Dostupné nástroje

generate_qr

Parametre

Volanie nástroja

Odpoveď

Príklady integrácie

Python (MCP SDK)

JavaScript (MCP SDK)

Vlastný klient (raw SSE + fetch)

Session management

Chybové kódy (JSON-RPC)

Príklady použitia

1. Jednoduchá platba za službu

2. Faktúra s dátumom splatnosti

3. Dobročinný dar s poznámkou

Podpora

Ďalšie zdroje

`generate_qr`