MCP Tools Reference
Complete reference for all 37 tools exposed by the Y.A.N.I. MCP Server. Each tool includes its schema, description, example JSON-RPC call, and security notes.
Overview
The Y.A.N.I. MCP Server exposes 37 tools organized in two categories based on their execution model and data source:
Advisory Tools (5)
Synchronous, knowledge-based tools that query the Y.A.N.I. knowledge base (50+ reference documents). They provide expert advice on finance, loyalty, identity, and banking without accessing user data.
Platform Tools (32)
Asynchronous, database-backed tools that query the YaniPay PostgreSQL database via Prisma ORM. They access real user data (wallets, transactions, KYC, etc.) and require email-based user identification.
Advisory Tools (5)
Advisory tools are synchronous and read from the Y.A.N.I. knowledge base — a curated collection of 50+ reference documents covering French fintech regulation, DOM fiscal specifics, loyalty programs, digital identity, and competitive banking analysis. They do not access any user data.
yani_financial_advice
Finance personnelle, bancaire, crypto et fiscalite DOM
Provides expert financial advice on personal finance, banking products, cryptocurrency strategies, savings optimization, and fiscal specifics for French overseas departments (DOM-TOM).
z.object({
query: z.string().describe("Question or request about finance"),
context: z.string().optional().describe("Additional context (e.g. location, situation)"),
topic: z.string().optional().describe("Specific topic: fiscalite, crypto, epargne, bancaire"),
}){
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "yani_financial_advice",
"arguments": {
"query": "Comment optimiser ma fiscalite?",
"topic": "fiscalite",
"context": "La Reunion, revenus 45000 EUR/an"
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "## Conseil Fiscal - La Reunion\n\nEn tant que resident de La Reunion (DOM), vous beneficiez d'avantages fiscaux specifiques:\n\n1. **Abattement fiscal DOM** : 30% sur l'IR (plafonne a 2450 EUR)\n2. **Reduction d'impot investissement** : Loi Girardin (jusqu'a 40%)\n3. **TVA reduite** : 8.5% (taux normal) vs 20% en metropole\n\n### Recommandations pour 45000 EUR/an\n- PEA avec ETF diversifies\n- Assurance-vie en fonds euros + UC\n- Defiscalisation Girardin si eligible"
}
]
}
}yani_loyalty_advice
Programmes fidelite, cashback, gamification
Expert advice on loyalty programs, cashback optimization, gamification strategies, points management, and reward program design for fintech applications.
z.object({
query: z.string().describe("Question about loyalty programs"),
context: z.string().optional().describe("Additional context"),
topic: z.string().optional().describe("Specific topic: cashback, gamification, fidelite"),
}){
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "yani_loyalty_advice",
"arguments": {
"query": "Comment structurer un programme de cashback competitif?",
"topic": "cashback"
}
}
}{
"jsonrpc": "2.0",
"id": 2,
"result": {
"content": [
{
"type": "text",
"text": "## Programme Cashback Competitif\n\n### Benchmarks marche\n- Revolut: 0.1-1% cashback\n- Curve: 1% (3 retailers)\n- YaniPay: jusqu'a 5% (commercants partenaires)\n\n### Structure recommandee\n1. **Base**: 0.5% sur tous les achats\n2. **Boosted**: 2-5% chez les partenaires\n3. **Tiers**: Bronze/Silver/Gold avec multiplicateurs\n4. **Gamification**: Challenges hebdomadaires (+0.5% bonus)"
}
]
}
}yani_identity_advice
KYC, verification identite, ZKP, RGPD
Expert guidance on identity verification, KYC processes, zero-knowledge proofs (ZKP) for privacy-preserving verification, RGPD compliance, biometric authentication, and digital identity standards.
z.object({
query: z.string().describe("Question about identity/KYC"),
context: z.string().optional().describe("Additional context"),
topic: z.string().optional().describe("Specific topic: kyc, rgpd, zkp, biometrie"),
}){
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "yani_identity_advice",
"arguments": {
"query": "Quels sont les niveaux de KYC requis pour une neobanque en France?",
"topic": "kyc"
}
}
}{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [
{
"type": "text",
"text": "## Niveaux KYC - Neobanque France\n\n### Niveau 1 : Simplifie (< 150 EUR/mois)\n- Email + telephone\n- Selfie + piece d'identite (recto)\n\n### Niveau 2 : Standard (< 10 000 EUR/mois)\n- Piece d'identite recto/verso\n- Justificatif de domicile < 3 mois\n- Video-verification (liveness check)\n\n### Niveau 3 : Renforce (illimite)\n- Entretien video avec agent\n- Justificatif de revenus\n- Source des fonds\n\n**Regulation**: AMF + ACPR, Directive LCB-FT 5"
}
]
}
}yani_banking_analysis
Analyse concurrentielle banques, neobanques, TPE, PSAN
Competitive analysis of traditional banks, neobanks, payment service providers (TPE), and crypto asset service providers (PSAN). Covers market positioning, pricing, features, and regulatory compliance.
z.object({
query: z.string().describe("Question about banking/neobank analysis"),
context: z.string().optional().describe("Additional context"),
topic: z.string().optional().describe("Specific topic: neobanque, tpe, psan, comparatif"),
}){
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "yani_banking_analysis",
"arguments": {
"query": "Comparaison des neobanques francaises pour les DOM-TOM",
"topic": "neobanque",
"context": "Marche ultramar"
}
}
}{
"jsonrpc": "2.0",
"id": 4,
"result": {
"content": [
{
"type": "text",
"text": "## Neobanques DOM-TOM - Analyse Comparative\n\n| Neobanque | Presence DOM | Carte | Frais FX | Crypto |\n|-----------|-------------|-------|----------|--------|\n| Revolut | Limitee | Visa | 0% | Oui |\n| N26 | Non | Visa | 0% | Non |\n| Nickel | Oui (Outremer) | MC | 1% | Non |\n| YaniPay | Natif DOM | Visa | 0% | Oui |\n\n### Avantage YaniPay\n- Concu pour les DOM-TOM\n- Fiscalite DOM integree\n- Programmes fidelite locaux"
}
]
}
}yani_search_knowledge
Recherche dans la base de connaissances Y.A.N.I.
Cross-skill search across the entire Y.A.N.I. knowledge base. Returns the top 5 most relevant results with skill category, filename, and a 500-character excerpt. Supports filtering by specific skill domain.
z.object({
query: z.string().describe("Search query"),
skill: z.enum(["financial", "loyalty", "identity", "banking", "all"])
.default("all")
.describe("Skill domain to search in"),
topic: z.string().optional().describe("Narrow down topic"),
}){
"jsonrpc": "2.0",
"id": 5,
"method": "tools/call",
"params": {
"name": "yani_search_knowledge",
"arguments": {
"query": "fiscalite DOM avantages",
"skill": "financial"
}
}
}{
"jsonrpc": "2.0",
"id": 5,
"result": {
"content": [
{
"type": "text",
"text": "## Resultats de recherche (5)\n\n### 1. fiscalite-dom-tom.md [financial]\nLes residents des DOM-TOM beneficient d'abattements fiscaux specifiques. L'abattement sur l'impot sur le revenu est de 30% pour La Reunion et la Guadeloupe (plafonne a 2 450 EUR), et de 40% pour la Guyane et Mayotte (plafonne a 4 050 EUR). La TVA est reduite...\n\n### 2. epargne-outremer.md [financial]\nLes produits d'epargne reglementee (Livret A, LDDS) sont identiques en metropole et dans les DOM...\n\n### 3. crypto-fiscalite-france.md [financial]\nLa flat tax de 30% s'applique aux plus-values crypto...\n\n### 4. girardin-investissement.md [financial]\nLe dispositif Girardin permet une reduction d'impot...\n\n### 5. comparatif-banques-dom.md [banking]\nLes frais bancaires dans les DOM sont en moyenne 30% plus eleves..."
}
]
}
}Platform Tools (32)
Platform tools are asynchronous and query the YaniPay PostgreSQL database via Prisma ORM. They access real user data identified by email address. All platform tools implement data sanitization to prevent exposure of sensitive fields (file URLs, private keys, IP addresses).
Security by Design
All platform tools sanitize sensitive data before returning results. Crypto addresses are truncated, S3 file URLs are never exposed, and PII fields (IP addresses, user agents, internal IDs) are stripped. See individual tool notes for details.
yani_get_balance
Soldes des wallets d'un utilisateur
Retrieves wallet balances for a user, with optional filtering by wallet type. Returns formatted balances with currency symbols and total aggregation.
z.object({
email: z.string().email().describe("User email address"),
wallet_type: z.enum(["EUROS", "EUROS_SAVINGS", "YANI_COIN", "BITCOIN", "ALL"])
.default("ALL")
.describe("Wallet type to query"),
}){
"jsonrpc": "2.0",
"id": 6,
"method": "tools/call",
"params": {
"name": "yani_get_balance",
"arguments": {
"email": "johan@yanipay.com",
"wallet_type": "ALL"
}
}
}{
"jsonrpc": "2.0",
"id": 6,
"result": {
"content": [
{
"type": "text",
"text": "## Soldes de Johan\n\n| Wallet | Solde | Devise |\n|--------|-------|--------|\n| EUROS | 1,234.56 | EUR |\n| EUROS_SAVINGS | 5,000.00 | EUR |\n| YANI_COIN | 500.00 | YANI |\n| BITCOIN | 0.0425 | BTC |\n\n**Total estime**: 7,834.56 EUR"
}
]
}
}yani_get_transactions
Transactions d'un utilisateur
Retrieves transaction history with filtering by wallet type and status. Includes aggregated statistics (total in/out, count by status). Limited to 1-100 results per call.
z.object({
email: z.string().email().describe("User email address"),
wallet_type: z.enum(["EUROS", "EUROS_SAVINGS", "YANI_COIN", "BITCOIN", "ALL"])
.default("ALL")
.describe("Filter by wallet type"),
status: z.enum(["PENDING", "COMPLETED", "FAILED", "CANCELLED", "ALL"])
.default("ALL")
.describe("Filter by transaction status"),
limit: z.number().min(1).max(100).default(20)
.describe("Number of transactions to return"),
}){
"jsonrpc": "2.0",
"id": 7,
"method": "tools/call",
"params": {
"name": "yani_get_transactions",
"arguments": {
"email": "johan@yanipay.com",
"wallet_type": "EUROS",
"status": "COMPLETED",
"limit": 10
}
}
}{
"jsonrpc": "2.0",
"id": 7,
"result": {
"content": [
{
"type": "text",
"text": "## Transactions EUROS (10 dernieres, COMPLETED)\n\n| Date | Type | Montant | Description |\n|------|------|---------|-------------|\n| 2026-02-20 | CREDIT | +150.00 EUR | Virement recu |\n| 2026-02-18 | DEBIT | -45.50 EUR | Paiement CB Carrefour |\n| 2026-02-15 | CREDIT | +2,500.00 EUR | Salaire |\n\n### Statistiques\n- Total entrant: +3,150.00 EUR\n- Total sortant: -485.50 EUR\n- Solde net: +2,664.50 EUR\n- Transactions: 10 COMPLETED / 2 PENDING / 0 FAILED"
}
]
}
}yani_get_payment_cards
Cartes de paiement
Retrieves all payment cards (physical and virtual) associated with a user account. Includes card status, type, spending limits, and masked card numbers.
z.object({
email: z.string().email().describe("User email address"),
}){
"jsonrpc": "2.0",
"id": 8,
"method": "tools/call",
"params": {
"name": "yani_get_payment_cards",
"arguments": {
"email": "johan@yanipay.com"
}
}
}{
"jsonrpc": "2.0",
"id": 8,
"result": {
"content": [
{
"type": "text",
"text": "## Cartes de paiement de Johan\n\n### 1. Carte UNIK Gold\n- Type: PHYSICAL\n- Numero: **** **** **** 4589\n- Status: ACTIVE\n- Plafond: 5,000 EUR/mois\n- Expire: 12/2028\n\n### 2. Carte Virtuelle\n- Type: VIRTUAL\n- Numero: **** **** **** 7721\n- Status: ACTIVE\n- Plafond: 1,000 EUR/mois\n- Expire: 06/2027"
}
]
}
}yani_get_loyalty_cards
Cartes de fidelite
Retrieves loyalty cards and reward program memberships. Includes points balance, tier level, cashback rates, and status filtering.
z.object({
email: z.string().email().describe("User email address"),
status: z.enum(["ACTIVE", "SUSPENDED", "EXPIRED", "CLOSED", "ALL"])
.default("ALL")
.describe("Filter by card status"),
}){
"jsonrpc": "2.0",
"id": 9,
"method": "tools/call",
"params": {
"name": "yani_get_loyalty_cards",
"arguments": {
"email": "johan@yanipay.com",
"status": "ACTIVE"
}
}
}{
"jsonrpc": "2.0",
"id": 9,
"result": {
"content": [
{
"type": "text",
"text": "## Cartes de fidelite (ACTIVE)\n\n### 1. Carrefour\n- Points: 2,450\n- Tier: Gold\n- Cashback: 3%\n- Status: ACTIVE\n\n### 2. FNAC\n- Points: 890\n- Tier: Silver\n- Cashback: 2%\n- Status: ACTIVE\n\n### 3. Sephora\n- Points: 1,200\n- Tier: Gold\n- Cashback: 5%\n- Status: ACTIVE\n\n**Total points**: 4,540"
}
]
}
}yani_get_stores
Stores et commercants
Retrieves stores and merchant profiles associated with a Pro user account. Includes store details, transaction volume, and connected loyalty programs.
z.object({
email: z.string().email().describe("User email address"),
}){
"jsonrpc": "2.0",
"id": 10,
"method": "tools/call",
"params": {
"name": "yani_get_stores",
"arguments": {
"email": "merchant@yanipay.com"
}
}
}{
"jsonrpc": "2.0",
"id": 10,
"result": {
"content": [
{
"type": "text",
"text": "## Stores de merchant@yanipay.com\n\n### 1. Boutique Saint-Denis\n- Categorie: Commerce de detail\n- CA mensuel: 12,450 EUR\n- Transactions: 342\n- Programme fidelite: Actif (245 membres)\n\n### 2. E-shop Reunion\n- Categorie: E-commerce\n- CA mensuel: 8,900 EUR\n- Transactions: 567\n- Programme fidelite: Actif (1,200 membres)"
}
]
}
}yani_tts_summary
Synthese vocale via ElevenLabs
Converts text to speech using the ElevenLabs API. Generates an audio summary that is played back to the user. Used by the Y.A.N.I. assistant to provide spoken feedback after completing tasks.
z.object({
message: z.string().describe("Text to convert to speech"),
context: z.string().optional().describe("Context for voice style (e.g. 'stop', 'alert')"),
}){
"jsonrpc": "2.0",
"id": 11,
"method": "tools/call",
"params": {
"name": "yani_tts_summary",
"arguments": {
"message": "Analyse terminee. Votre portefeuille a augmente de 5% cette semaine.",
"context": "stop"
}
}
}{
"jsonrpc": "2.0",
"id": 11,
"result": {
"content": [
{
"type": "text",
"text": "Audio genere et lu avec succes (ElevenLabs TTS).\nMessage: Analyse terminee. Votre portefeuille a augmente de 5% cette semaine."
}
]
}
}yani_get_kyc_status
Statut KYC utilisateur
Retrieves KYC (Know Your Customer) submission status and document verification progress. Supports filtering by verification status.
z.object({
email: z.string().email().describe("User email address"),
status: z.enum(["PENDING", "IN_REVIEW", "VALIDATED", "REJECTED", "EXPIRED", "ALL"])
.default("ALL")
.describe("Filter by KYC status"),
}){
"jsonrpc": "2.0",
"id": 12,
"method": "tools/call",
"params": {
"name": "yani_get_kyc_status",
"arguments": {
"email": "johan@yanipay.com",
"status": "ALL"
}
}
}{
"jsonrpc": "2.0",
"id": 12,
"result": {
"content": [
{
"type": "text",
"text": "## Statut KYC de Johan\n\n### Soumission #1\n- Status: VALIDATED\n- Type: IDENTITY_CARD\n- Document: carte-identite-recto.jpg\n- Soumis: 2026-01-10\n- Valide: 2026-01-11\n\n### Soumission #2\n- Status: VALIDATED\n- Type: PROOF_OF_ADDRESS\n- Document: facture-edf.pdf\n- Soumis: 2026-01-10\n- Valide: 2026-01-12\n\n### Resume\n- Niveau KYC: 2 (Standard)\n- Documents valides: 2/2\n- Prochaine expiration: 2027-01-10"
}
]
}
}Security: fileUrl never exposed
The fileUrl field (S3 signed URL) is never included in the response. Only the fileName is returned to prevent direct access to identity documents.
yani_get_crypto_wallets
Wallets crypto internes + externes
Retrieves both internal YaniPay crypto wallets and externally connected wallets (MetaMask, Ledger, etc.). Optionally includes external wallets via the include_external flag.
z.object({
email: z.string().email().describe("User email address"),
include_external: z.boolean().default(true)
.describe("Include externally connected wallets"),
}){
"jsonrpc": "2.0",
"id": 13,
"method": "tools/call",
"params": {
"name": "yani_get_crypto_wallets",
"arguments": {
"email": "johan@yanipay.com",
"include_external": true
}
}
}{
"jsonrpc": "2.0",
"id": 13,
"result": {
"content": [
{
"type": "text",
"text": "## Wallets Crypto de Johan\n\n### Wallets Internes\n| Chain | Adresse | Solde |\n|-------|---------|-------|\n| YaniChain | 0x742d...aDF3 | 500.00 YANI |\n| Ethereum | 0x1234...abcd | 0.85 ETH |\n| Bitcoin | bc1q...xyz9 | 0.0425 BTC |\n\n### Wallets Externes\n| Provider | Chain | Adresse |\n|----------|-------|---------|\n| MetaMask | Ethereum | 0x9876...ef01 |\n| Ledger | Bitcoin | bc1q...mnop |\n\n**Total interne estime**: 2,450 EUR"
}
]
}
}Security: Addresses truncated, publicKey never exposed
All blockchain addresses are truncated to the format 0x1234...abcd (first 6 + last 4 characters). The publicKey field is never included in the response to prevent wallet impersonation.
yani_get_referrals
Liens de parrainage
Retrieves referral links, codes, and conversion statistics. Optionally includes detailed conversion data (signups, activations, rewards earned).
z.object({
email: z.string().email().describe("User email address"),
include_conversions: z.boolean().default(true)
.describe("Include conversion statistics"),
}){
"jsonrpc": "2.0",
"id": 14,
"method": "tools/call",
"params": {
"name": "yani_get_referrals",
"arguments": {
"email": "johan@yanipay.com",
"include_conversions": true
}
}
}{
"jsonrpc": "2.0",
"id": 14,
"result": {
"content": [
{
"type": "text",
"text": "## Parrainage de Johan\n\n### Code de parrainage\n- Code: JOHAN-YANI-2026\n- Lien: https://yanipay.com/ref/JOHAN-YANI-2026\n- Reward parrain: 10 EUR\n- Reward filleul: 5 EUR\n\n### Conversions\n| Date | Statut | Reward |\n|------|--------|--------|\n| 2026-02-15 | ACTIVATED | +10 EUR |\n| 2026-02-10 | SIGNED_UP | En attente |\n| 2026-01-28 | ACTIVATED | +10 EUR |\n\n### Statistiques\n- Total parraines: 12\n- Actives: 8\n- En attente: 4\n- Rewards gagnes: 80 EUR"
}
]
}
}Security: PII fields stripped
The following fields are never included in the response: refereeId, ipAddress, userAgent. Conversion data is anonymized to prevent identification of referred users.
CLI Testing
The Y.A.N.I. MCP Server includes a CLI tool (yani-query.sh) for testing all 37 tools directly from the terminal. This is useful for development, debugging, and verifying tool responses before integrating with an LLM client.
./yani-query.sh --list
# Output:
# Available tools (37):
#
# Advisory Tools (5):
# 1. yani_financial_advice - Finance personnelle, bancaire, crypto et fiscalite DOM
# 2. yani_loyalty_advice - Programmes fidelite, cashback, gamification
# 3. yani_identity_advice - KYC, verification identite, ZKP, RGPD
# 4. yani_banking_analysis - Analyse concurrentielle banques, neobanques, TPE, PSAN
# 5. yani_search_knowledge - Recherche dans la base de connaissances Y.A.N.I.
#
# Platform Tools (32):
# 6. yani_get_balance - Soldes des wallets d'un utilisateur
# 7. yani_get_transactions - Transactions d'un utilisateur
# 8. yani_get_payment_cards - Cartes de paiement
# 9. yani_get_loyalty_cards - Cartes de fidelite
# 10. yani_get_stores - Stores et commercants
# 11. yani_tts_summary - Synthese vocale via ElevenLabs
# 12. yani_get_kyc_status - Statut KYC utilisateur
# 13. yani_get_crypto_wallets - Wallets crypto internes + externes
# 14. yani_get_referrals - Liens de parrainage# Financial advice
./yani-query.sh yani_financial_advice \
--query "Comment optimiser ma fiscalite a La Reunion?" \
--topic "fiscalite" \
--context "La Reunion, revenus 45000 EUR/an"
# Search knowledge base across all skills
./yani-query.sh yani_search_knowledge \
--query "avantages fiscaux DOM" \
--skill "all"
# Banking competitive analysis
./yani-query.sh yani_banking_analysis \
--query "Comparaison neobanques DOM" \
--topic "neobanque"# Get wallet balances
./yani-query.sh yani_get_balance \
--email johan@yanipay.com \
--wallet_type ALL
# Get transactions with filters
./yani-query.sh yani_get_transactions \
--email johan@yanipay.com \
--wallet_type EUROS \
--status COMPLETED \
--limit 10
# Get KYC status
./yani-query.sh yani_get_kyc_status \
--email johan@yanipay.com \
--status ALL
# Get crypto wallets with externals
./yani-query.sh yani_get_crypto_wallets \
--email johan@yanipay.com \
--include_external true
# Get referral stats
./yani-query.sh yani_get_referrals \
--email johan@yanipay.com \
--include_conversions true
# Generate TTS summary
./yani-query.sh yani_tts_summary \
--message "Analyse terminee. 3 taches completees."Error Handling
All tools return errors in a consistent format following the MCP specification. Errors include a human-readable message and, for platform tools, a machine-readable error code.
Error Response Format
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "Erreur: Utilisateur non trouve pour l'email: unknown@example.com"
}
],
"isError": true
}
}Common Error Scenarios
| Scenario | Tool Category | Error Message |
|---|---|---|
| User not found | Platform | Utilisateur non trouve pour l'email: ... |
| No wallets found | Platform | Aucun wallet trouve pour cet utilisateur |
| Invalid email format | Platform | Validation error: Invalid email |
| Knowledge base empty | Advisory | Aucun resultat trouve pour cette recherche |
| Database connection error | Platform | Erreur interne: impossible de se connecter a la base |
| TTS API failure | Platform | Erreur TTS: ElevenLabs API non disponible |
// Handle MCP tool errors in your client
const result = await mcpClient.callTool("yani_get_balance", {
email: "user@example.com",
wallet_type: "ALL",
});
if (result.isError) {
// Tool returned an error
console.error("Tool error:", result.content[0].text);
// Show user-friendly message
return "Unable to retrieve balance. Please try again.";
}
// Process successful result
const markdown = result.content[0].text;
return formatForUser(markdown);