# ISX Financial — AI Merchant Onboarding (agent documentation)

ISX is a Cyprus-based electronic money institution (EMI) offering e-money accounts, merchant acquiring, and payment processing to EU businesses. This capability provides AI-native KYB (business) and UBO KYC (beneficial-owner) merchant onboarding.

This document is optimized for LLM consumption. No marketing.

## Terminology
- **KYB** — Know Your Business (the merchant entity).
- **UBO** — Ultimate Beneficial Owner (a natural person who owns/controls the merchant); each needs KYC.
- **Case** — one onboarding application, bound to the authenticated user.
- **Attestation** — an unverified fact the user asserts (`merchant.*` or `ubo.*`); may reference uploaded documents.
- **Aggregate** — the derived, current set of attested facts. **Checklist** — requirements/status derived from the aggregate by the backend.

## Authentication
- Connect to the MCP endpoint `https://mcp.mykyc.io/mcp` (Streamable HTTP).
- The server is its own OAuth 2.1 authorization server (issuer `https://mcp.mykyc.io`): dynamic client registration (`/register`), authorization code + PKCE (`/authorize`, `/token`).
- Identity is derived server-side from the validated token. Every case is owned by that identity; cross-user access is rejected.

## Onboarding flow
1. `describe_context` — read ISX overview, the requirement/fact catalogue, and Terms & Conditions.
2. `start_merchant_onboarding` — create a case (this accepts the current T&Cs).
3. `request_document_upload_urls` + PUT the bytes to the returned signed URL.
4. `submit_attested_evidence` — submit facts (attest/retract/retract_subject) with optional document references. The reply carries fresh case state (no polling). Optionally `validate_evidence` first to dry-run a payload.
5. `get_case_state` — re-read the checklist, risk level, and what is still missing.
6. `submit_application` — only when `case_status` is `ready_to_submit`.

The backend decides which requirements apply and computes risk deterministically. Do not decide requirements yourself; ask and submit. Confirm with the user before every submission.

## Tools
- `describe_context` — ISX/product overview, onboarding flow, requirement catalogue, MCP surface, contacts, and Terms & Conditions. Call first.
- `start_merchant_onboarding` — Create an onboarding case (accepts the current T&Cs).
- `request_document_upload_urls` — Create document placeholders and return signed upload URLs.
- `submit_attested_evidence` — Submit attested KYB/UBO facts (attest/retract/retract_subject) with optional document references.
- `get_case_state` — Latest checklist, risk level, missing evidence, and recent submission statuses for a case.
- `submit_application` — Submit the application (only when ready_to_submit).
- `list_cases` — List the authenticated user's onboarding cases with a per-case summary.
- `get_case_detail` — Latest aggregate + document manifest for one case.
- `validate_evidence` — Dry-run a proposed evidence payload against edge validation without submitting it.
- `get_document_download_url` — Get a short-lived signed URL to read back an uploaded document.
- `get_case_history` — The case's full ordered timeline of submissions and status changes.
- `close_case` — Withdraw a case; the case is closed permanently (terminal).

## Rules
- All user data is unverified; only `merchant.*`/`ubo.*` fact types are accepted.
- At least one UBO is always required. Risk is `pending`/`low`/`high`; sanctioned jurisdictions are declined (terminal).
- Documents are WORM. Read a stored document back with `get_document_download_url`.
- `close_case` withdraws a case permanently.

## Example (first call after auth)
```
tools/call describe_context {}
tools/call start_merchant_onboarding { "merchant_name": "Acme Cyprus Ltd", "merchant_country": "CY", "business_activity": "Professional services" }
```

## More
- Human documentation: https://mcp.mykyc.io/ai/docs
- AI manifest: https://mcp.mykyc.io/.well-known/isx-ai.json
- MCP manifest: https://mcp.mykyc.io/.well-known/mcp.json
- OpenAPI: https://mcp.mykyc.io/openapi.json