AI / Agent API (MCP)

Beyond the admin panel, Intelligent Merchant Monitoring checks and reference data are available programmatically — so your AI assistant, a compliance-officer chatbot, or external automation can call them. Access is read-only, secured by a token.

There are two ways to connect — both expose the same capabilities:

MCP server (POST https://admin.shield.by/mcp) — over the Model Context Protocol (MCP), Streamable HTTP. Your bank’s AI assistant (Claude, Open WebUI, any MCP-compatible client) sees the checks as native tools and calls them itself during a conversation.
REST API v1 (https://admin.shield.by/api/v1/...) — the same checks over plain HTTP, to wire into any stack.

What’s available (13 tools)

Reference

get_mcc / search_mcc — MCC card by code and search by description.
get_oked / search_oked / oked_children — OKED directory (OKRB 005‑2011), search and child codes.
expected_mcc — expected MCCs for an OKED code (activity → acquiring code mapping).

Entity checks

egr — business registry (EGR, Belarus) lookup by UNP.
trade_register — presence in the Trade Register (MART).
aml — sanctions / AML list screening (OpenSanctions).
fatf — FATF country risk.
mcc_suggest — AI MCC detection from a website: reads the content and suggests an MCC with a miscoding verdict, grounded in the real code catalogue (RAG); tells services apart from goods.

Case aggregates

case_checks — current state of all indicators on an underwriting case.
case_report — data for the final case report (for an LLM composer).

Authorization

Every request carries an Authorization: Bearer <token> header. Two levels:

Token	Grants
Global read token	reference only (MCC, OKED, expected‑mcc)
Per-tenant token	reference + checks + cases for that tenant

The per-tenant token is issued in the admin panel on the tenant page. Rate limits apply.

Uniform response envelope

Every response uses one envelope:

{
  "schema_version": "1.0",
  "data": { "mcc": "5812", "category": "Restaurants", "confidence": 0.95, "...": "..." },
  "meta": { "source": "mistral", "status": "grey", "summary": "...", "cost_hint": "metered" }
}

data — the check result.
meta.status — a traffic light (green / grey / red) for quick interpretation.
meta.source — where the data came from (catalogue, EGR, mistral, …); cost_hint — free/metered.

Example: REST

# Suggest an MCC from a merchant website
curl -H "Authorization: Bearer $WEBSHIELD_TOKEN" \
  "https://admin.shield.by/api/v1/mcc-suggest?url=https://example-shop.by"

# Business registry (EGR) lookup by UNP
curl -H "Authorization: Bearer $WEBSHIELD_TOKEN" \
  "https://admin.shield.by/api/v1/egr/123456789"

Example: connecting MCP to an AI assistant

In an MCP-compatible client (Claude, Open WebUI, Cursor, MCP Inspector) add the server:

Transport: Streamable HTTP
URL: https://admin.shield.by/mcp
Auth: Bearer, your platform token

Once connected, the assistant calls the right tool during the chat — e.g. for “determine the MCC for site X” it will invoke mcc_suggest and return the answer with sources.