Skip to main content
Nasz serwer Model Context Protocol pozwala dowolnemu klientowi MCP (np. Claude Desktop, Claude Code, innym agentom LLM) łączyć się bezpośrednio z agentem w Agent Panel, przeglądać katalog produktów i płacić za nie BLIK-iem w jego imieniu - każda płatność jest osobno potwierdzana przez użytkownika kodem BLIK w aplikacji bankowej.
Serwer obsługuje też protokół x402 do w pełni automatycznych płatności (bez potwierdzenia BLIK), ale to narzędzie jest na ten moment wyłączone - patrz sekcję Dostępne narzędzia poniżej.

​
1. Klucz API

Każdy agent (portfel) ma własny klucz API, widoczny w Agent Panel w zakładce Ustawienia → Klucze API. Klucz jest tworzony razem z portfelem agenta i wykorzystywany do uwierzytelniania sesji MCP.

​
2. Uruchomienie serwera lokalnie

Serwer MCP to część agent-facilitator (npm run mcp, w Dockerze uruchamiany razem z główną usługą - patrz Dockerfile). Musi mieć dostęp do dwóch rzeczy, żeby narzędzia płatnicze działały:

​
3. Konfiguracja klienta MCP

​
Claude Code / Claude CLI

Najprostszy sposób - serwer wspiera natywny transport HTTP, więc nie jest potrzebny żaden dodatkowy wrapper:
  • --transport http - wskazuje na Streamable HTTP (nie SSE, nie stdio)
  • http://localhost:4021/mcp - adres serwera; w środowisku innym niż lokalne (staging/prod) podmień na właściwy host, na którym działa proces npm run mcp z agent-facilitator (domyślny port to 4021, konfigurowalny przez zmienną MCP_PORT)
  • --header "x-api-key: ..." - klucz API agenta z Agent Panel (krok 1)
  • --scope user - serwer dostępny we wszystkich projektach danego użytkownika Claude Code (użyj --scope project, jeśli ma być widoczny tylko w jednym repo)
Po dodaniu serwer widoczny jest na liście claude mcp list, a narzędzia (list_products, process_blik_payment, check_payment_status, list_transactions) - w rozmowie z Claude Code.

​
Custom connector (Claude.ai, Claude Desktop, Cowork, aplikacje mobilne)

Działa we wszystkich klientach Claude poza Claude Code, bez żadnej konfiguracji lokalnej. Connector łączy się z serwerem z chmury Anthropic, nie z Twojego urządzenia, więc serwer musi mieć publiczny adres - localhost nie zadziała. Do lokalnego developmentu użyj Claude Code (sekcja wyżej).
  1. Otwórz ustawienia connectorów:
    a) Free/Pro/Max: Customize → Connectors → “Add custom connector”.
    b) Team/Enterprise: Owner dodaje connector w Organization settings → Connectors → Add → Custom → Web, a każdy użytkownik włącza go potem u siebie w Customize → Connectors.
  2. Podaj adres serwera: https://<adres-serwera-mcp>/mcp.
  3. W Request headers dodaj nagłówek x-api-key z kluczem API agenta i zaznacz go jako Required.
  4. Kliknij Add, a potem włącz connector w rozmowie przyciskiem ”+” → Connectors.
Uwierzytelnianie przez nagłówki (Request headers) jest funkcją w becie i może nie być jeszcze widoczne na Twoim koncie - jeśli tak, poproś Anthropic o dostęp.

​
Dostępne narzędzia

Narzędzia fetch_x402_resource (automatyczna płatność x402 z salda portfela), check_wallet_balance (saldo portfela + status guardrails) oraz buy_via_acp (automatyczna płatność u merchanta Agentic Commerce Protocol, również z salda portfela) są tymczasowo wyłączone w kodzie serwera. MCP obsługuje obecnie wyłącznie katalog produktów i płatność BLIK, każdorazowo potwierdzaną przez użytkownika.

​
list_products

Zwraca katalog dostępnych produktów (id, nazwa, cena w PLN i w groszach). Nie przyjmuje parametrów. id z odpowiedzi jest wymagany do wywołania process_blik_payment.

​
process_blik_payment

Płaci BLIK-iem za wybrany produkt w imieniu agenta przypisanego do klucza API. To osobna, świeża płatność potwierdzana kodem BLIK przy każdym zakupie - nie jest pobierana z żadnego zgromadzonego wcześniej salda. Cena jest pobierana samodzielnie z katalogu na podstawie productId (LLM nie podaje jej ręcznie - eliminuje to błędy przy przeliczaniu na grosze). Narzędzie tylko inicjuje płatność i zwraca txId oraz externalId - wynik nie jest jeszcze znany w tym momencie.
Po process_blik_payment agent musi wywołać check_payment_status zanim poinformuje użytkownika o wyniku. Sam brak błędu przy inicjacji płatności nie oznacza sukcesu.
txId można pokazać użytkownikowi jako numer referencyjny. externalId jest wyłącznie techniczny - służy do wywołania check_payment_status i nie powinien być pokazywany ani wspominany użytkownikowi.

​
check_payment_status

Sprawdza rzeczywisty wynik wcześniej zainicjowanej płatności BLIK. Zwraca status: pending, completed albo failed. Dopóki status to pending, agent powinien odczekać kilka sekund i sprawdzić ponownie (maks. ok. 10 razy) zamiast informować użytkownika o wyniku.

​
list_transactions

Zwraca historię transakcji portfela przypisanego do klucza API, od najnowszej. Obsługuje opcjonalny zakres dat, np. żeby sprawdzić zakupy z konkretnego kwartału - samo from bez to zwraca wszystko od podanej daty do dziś. Każdy wpis zawiera datę, status, nazwę produktu (jeśli dostępna), kwotę i txId - przydatne, żeby agent mógł odpowiedzieć na pytania w stylu “co ostatnio kupiłem” albo “co kupiłem w Q1”, albo sprawdzić, czy dane zamówienie nie zostało już zrealizowane, zanim spróbuje zapłacić ponownie.
Jeśli wyników jest więcej niż zwrócony limit, odpowiedź narzędzia zawiera na końcu informację, ile transakcji zostało jeszcze do pokazania. Agent powinien wtedy zapytać użytkownika, czy pokazać kolejne, a nie automatycznie pobierać wszystkie kolejne strony.
Guardrails (limity godzinowe/dobowe) można skonfigurować w ustawieniach portfela, ale nic w aplikacji nie sprawdza faktycznych wydatków względem tych limitów. Realną granicą jest dziś to, że każdą płatność musi osobno potwierdzić człowiek kodem BLIK.