Integration Guide

Connecting LLMs to YaniPay

Step-by-step instructions for integrating with the Y.A.N.I. MCP Server using stdio, HTTP/SSE, or REST API transports. From Claude Code to custom Python clients, every integration path is covered.

stdio

Direct pipe for Claude Code. Zero latency, auto-discovery of all 37 tools.

HTTP/SSE

Streamable HTTP on port 3100. Session-based with API key auth for web clients.

REST API

Simple REST on port 3101. Universal query auto-routing, OpenAI function schema.

Prerequisites

Before integrating with the Y.A.N.I. MCP Server, ensure you have the following installed and configured:

Node.js 20+

Required runtime. Check with node --version

pnpm

Package manager. Install with npm install -g pnpm

PostgreSQL

Database server running locally or remotely

DATABASE_URL

Connection string configured in environment

Verify prerequisitesbash

# Check Node.js version (must be 20+)
node --version

# Check pnpm
pnpm --version

# Check PostgreSQL
psql --version

# Verify DATABASE_URL is set
echo $DATABASE_URL

Claude Code Integration (stdio)

The stdio transport is the recommended integration for Claude Code. It communicates via stdin/stdout pipes with zero network overhead. Claude Code automatically discovers all 37 tools, 3 resources, and 3 prompts.

1. Configure Claude Code

Add the MCP server to your project's .claude/settings.json:

.claude/settings.jsonjson

{
  "mcpServers": {
    "yani-advisor": {
      "command": "npx",
      "args": ["tsx", "mcp-server-yani/src/index.ts"],
      "cwd": "/path/to/yanipay-animation",
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/yanipay"
      }
    }
  }
}

2. Build the server

Compile the TypeScript source to JavaScript for production use:

Build stepsbash

cd mcp-server-yani

# Install dependencies
pnpm install

# Generate Prisma client (required for platform tools)
npx prisma generate

# Build TypeScript to dist/
pnpm build

For development, you can skip the build step since the settings.json uses npx tsx which compiles TypeScript on-the-fly.

3. Verify tool discovery

Once configured, Claude Code will automatically detect the MCP server on startup. You should see 37 tools listed under the MCP status. Verify by asking Claude Code to list its available tools:

Claude Code auto-discoverytext

MCP servers: yani-advisor (37 tools)

Advisory tools (5):
  - yani_financial_advice      Finance, fiscal, crypto, epargne
  - yani_loyalty_advice        Fidelite, cashback, gamification
  - yani_identity_advice       KYC, RGPD, ZKP, biometrie
  - yani_banking_analysis      Neobanques, TPE, PSAN comparatif
  - yani_search_knowledge      Recherche cross-skills dans la KB

Platform tools (9):
  - yani_get_balance           Soldes wallets EUR/YANI/BTC
  - yani_get_transactions      Historique avec stats aggregees
  - yani_get_payment_cards     Cartes physiques et virtuelles
  - yani_get_loyalty_cards     Programmes fidelite et points
  - yani_get_stores            Stores et commercants Pro
  - yani_tts_summary           Synthese vocale ElevenLabs
  - yani_get_kyc_status        Soumissions KYC et documents
  - yani_get_crypto_wallets    Wallets crypto internes + externes
  - yani_get_referrals         Parrainage, codes et conversions

4. Usage examples

Once connected, you can use natural language in Claude Code. The AI will automatically select and call the right MCP tools:

Natural language queries in Claude Codetext

# Financial advice
"What are the tax benefits for YaniPay users in La Reunion?"

# Wallet balance check
"Show me the wallet balances for user@example.com"

# Transaction history with stats
"Get the last 10 completed transactions for dev@example.com"

# KYC status
"What is the KYC verification status for this user?"

# Loyalty programs
"How many loyalty points does user@example.com have?"

# Competitive analysis
"Compare YaniPay fees with Revolut and N26 for DOM users"

# Knowledge base search
"Search the knowledge base for information about PSAN regulation"

HTTP/SSE Integration (port 3100)

The HTTP/SSE transport exposes the full MCP protocol over HTTP using the Streamable HTTP specification. It supports session management, server-sent events for streaming, and optional API key authentication.

1. Start the HTTP server

Start HTTP/SSE serverbash

# Using pnpm scripts (after building)
cd mcp-server-yani
pnpm start:http

# Or with a custom port
PORT=3100 node dist/server-http.js

# For development (with hot reload)
pnpm dev:http

2. Health check

Verify the server is running and inspect its capabilities:

Health checkbash

curl http://localhost:3100/health | jq

Health check responsejson

{
  "status": "ok",
  "server": "yani-advisor",
  "version": "1.2.0",
  "transport": "streamable-http",
  "sessions": 0,
  "auth": "open",
  "advisory": [
    "yani_financial_advice",
    "yani_loyalty_advice",
    "yani_identity_advice",
    "yani_banking_analysis",
    "yani_search_knowledge"
  ],
  "platform": [
    "yani_get_balance",
    "yani_get_loyalty_cards",
    "yani_get_stores",
    "yani_get_transactions",
    "yani_get_payment_cards",
    "yani_tts_summary",
    "yani_get_kyc_status",
    "yani_get_crypto_wallets",
    "yani_get_referrals"
  ],
  "resources": ["yani://config", "yani://models/{model}", "yani://knowledge/{skill}"],
  "prompts": ["analyse_financiere_utilisateur", "resume_portefeuille", "diagnostic_kyc"]
}

3. Session workflow

The HTTP transport uses JSON-RPC 2.0 over HTTP. Each client session follows a three-step lifecycle: initialize, call tools, and terminate.

Initialize session

POST /mcp (no session-id header)

Call tools

POST /mcp with mcp-session-id header

Terminate session

DELETE /mcp with mcp-session-id header

Step 1: Initialize a session

Initialize MCP sessionbash

# Send initialize request (no session-id header = new session)
curl -X POST http://localhost:3100/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "my-client",
        "version": "1.0.0"
      }
    }
  }' \
  -v 2>&1 | grep -i "mcp-session-id"

# Response header contains: mcp-session-id: <uuid>
# Save this session ID for subsequent requests

Step 2: Call tools with session ID

Call a tool via HTTP/SSEbash

# Replace <session-id> with the UUID from Step 1

# First send the initialized notification
curl -X POST http://localhost:3100/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: <session-id>" \
  -d '{
    "jsonrpc": "2.0",
    "method": "notifications/initialized"
  }'

# Then call a tool
curl -X POST http://localhost:3100/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: <session-id>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "yani_financial_advice",
      "arguments": {
        "query": "Comment optimiser ma fiscalite a La Reunion?",
        "topic": "fiscalite"
      }
    }
  }'

Step 3: Terminate the session

Terminate MCP sessionbash

curl -X DELETE http://localhost:3100/mcp \
  -H "mcp-session-id: <session-id>"

# Response: { "status": "session_terminated" }

4. API key authentication

To secure the HTTP endpoint, set the MCP_API_KEY environment variable. When set, all requests to /mcp must include an Authorization: Bearer header. The /health endpoint remains open.

Enable API key authbash

# Start with API key authentication enabled
MCP_API_KEY="your-secret-key-here" pnpm start:http

# Requests must include the Bearer token
curl -X POST http://localhost:3100/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-key-here" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "my-client", "version": "1.0.0" }
    }
  }'

# Without the key, you get a 401:
# { "jsonrpc": "2.0", "error": { "code": -32001, "message": "Missing Authorization: Bearer <key>" } }

REST API Integration (port 3101)

The REST API provides simple HTTP endpoints that any LLM or application can call without understanding the MCP protocol. It includes auto-routing, rate limiting (100 req/min/IP), CORS support, and OpenAI-compatible function definitions.

1. Start the REST API server

Start REST API serverbash

# Using pnpm scripts (after building)
cd mcp-server-yani
pnpm start:api

# Or with a custom port
PORT=3101 node dist/server-api.js

# For development (with hot reload)
pnpm dev:api

2. Available endpoints

Method	Endpoint	Description
GET	/	API documentation and tool list
GET	/health	Health check with tool counts
GET	/tools	List all tools with schemas
POST	/tools/:name	Call a specific tool by name
POST	/query	Universal query with auto-routing
GET	/openapi.json	OpenAI-compatible function definitions

3. Calling advisory tools

Advisory tools accept a query string and optional context and topic parameters:

Call an advisory toolbash

# Financial advice
curl -X POST http://localhost:3101/tools/yani_financial_advice \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Comment optimiser ma fiscalite en tant que micro-entrepreneur a La Reunion?",
    "context": "La Reunion",
    "topic": "fiscalite"
  }'

# Loyalty strategy
curl -X POST http://localhost:3101/tools/yani_loyalty_advice \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How to design a cashback program for local merchants?",
    "topic": "cashback"
  }'

# Banking competitive analysis
curl -X POST http://localhost:3101/tools/yani_banking_analysis \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Compare neobank fees: Revolut vs N26 vs YaniPay for DOM users"
  }'

4. Calling platform tools

Platform tools query the PostgreSQL database. They accept email to identify the user and optional filters:

Call platform toolsbash

# Get wallet balances
curl -X POST http://localhost:3101/tools/yani_get_balance \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "wallet_type": "ALL"
  }'

# Get transaction history with stats
curl -X POST http://localhost:3101/tools/yani_get_transactions \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "limit": 10,
    "status": "COMPLETED",
    "include_stats": true
  }'

# Get KYC status
curl -X POST http://localhost:3101/tools/yani_get_kyc_status \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com"
  }'

# Get crypto wallets
curl -X POST http://localhost:3101/tools/yani_get_crypto_wallets \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "include_external": true
  }'

# Get referral data
curl -X POST http://localhost:3101/tools/yani_get_referrals \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "include_conversions": true
  }'

5. Universal query with auto-routing

The POST /query endpoint analyzes your question and automatically routes it to the most relevant advisory tool based on keyword matching. This is ideal for chat interfaces where the user does not know which tool to call.

Universal querybash

# Auto-routed to yani_financial_advice (matches "fiscalite", "impot")
curl -X POST http://localhost:3101/query \
  -H "Content-Type: application/json" \
  -d '{ "query": "Quels sont les avantages fiscaux de la defiscalisation Girardin?" }'

# Auto-routed to yani_loyalty_advice (matches "fidelite", "cashback")
curl -X POST http://localhost:3101/query \
  -H "Content-Type: application/json" \
  -d '{ "query": "Comment fonctionne le programme de fidelite cashback?" }'

# Auto-routed to yani_identity_advice (matches "kyc", "verification")
curl -X POST http://localhost:3101/query \
  -H "Content-Type: application/json" \
  -d '{ "query": "Quelles sont les etapes de verification KYC?" }'

The auto-routing uses keyword scoring across these categories:

Tool	Routing keywords
yani_financial_advice	fiscalite, impot, epargne, credit, crypto, bitcoin, investissement, placement, pea, budget, girardin, pinel, patrimoine
yani_loyalty_advice	fidelite, cashback, points, programme, gamification, coupon, recompense, loyalty, parrainage
yani_identity_advice	kyc, identite, verification, cni, passeport, rgpd, zkp, biometrie, pvid, franceconnect, aml
yani_banking_analysis	banque, neobanque, tpe, terminal, psan, paiement, revolut, n26, boursobank, nickel, wise, comparatif
yani_search_knowledge	recherche, chercher, trouver, search, knowledge, documentation, reference

6. OpenAI function calling integration

The GET /openapi.jsonendpoint returns tool definitions in a format compatible with OpenAI's function calling API. You can feed this directly to GPT-4, Gemini, or any LLM that supports function calling:

OpenAI function calling integrationtypescript

import OpenAI from 'openai';

const openai = new OpenAI();

// 1. Fetch tool definitions from Y.A.N.I. REST API
const res = await fetch('http://localhost:3101/openapi.json');
const schema = await res.json();

// 2. Convert to OpenAI function format
const tools = schema.functions.map((fn: any) => ({
  type: 'function' as const,
  function: {
    name: fn.name,
    description: fn.description,
    parameters: fn.parameters,
  },
}));

// 3. Call OpenAI with Y.A.N.I. tools
const completion = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'What are the tax benefits in La Reunion?' }],
  tools,
});

// 4. If the LLM wants to call a tool, forward to Y.A.N.I.
const toolCall = completion.choices[0].message.tool_calls?.[0];
if (toolCall) {
  const toolResult = await fetch(
    `http://localhost:3101/tools/${toolCall.function.name}`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: toolCall.function.arguments,
    }
  );
  const data = await toolResult.json();
  console.log(data.response);
}

CLI Testing with yani-query.sh

The yani-query.sh CLI script is the fastest way to test all 37 tools from your terminal. It communicates directly with the MCP server via stdio (no HTTP server needed).

Usage syntax

CLI usagebash

# Show help
./mcp-server-yani/yani-query.sh --help

# List all 37 tools
./mcp-server-yani/yani-query.sh --list

Advisory tools

Advisory tools accept --query (required), plus optional --context and --topic:

Advisory tool examplesbash

# Financial advice with topic
./mcp-server-yani/yani-query.sh yani_financial_advice \
  --query "Comment optimiser ma fiscalite?" \
  --topic fiscalite

# Loyalty strategy with context
./mcp-server-yani/yani-query.sh yani_loyalty_advice \
  --query "Creer un programme fidelite" \
  --context "La Reunion"

# Identity / KYC advice
./mcp-server-yani/yani-query.sh yani_identity_advice \
  --query "Quelles pieces justificatives pour un KYC niveau 2?"

# Banking competitive analysis
./mcp-server-yani/yani-query.sh yani_banking_analysis \
  --query "Compare les frais de Revolut et N26 pour les DOM"

# Search the knowledge base
./mcp-server-yani/yani-query.sh yani_search_knowledge \
  --query "fiscalite DOM"

Platform tools

Platform tools require --email and support additional filters:

Platform tool examplesbash

# Get wallet balances
./mcp-server-yani/yani-query.sh yani_get_balance \
  --email dev@example.com

# Filter by wallet type
./mcp-server-yani/yani-query.sh yani_get_balance \
  --email dev@example.com \
  --wallet-type EUROS

# Get transactions with filters
./mcp-server-yani/yani-query.sh yani_get_transactions \
  --email dev@example.com \
  --limit 10 \
  --status COMPLETED

# Get payment cards
./mcp-server-yani/yani-query.sh yani_get_payment_cards \
  --email dev@example.com

# Get loyalty cards
./mcp-server-yani/yani-query.sh yani_get_loyalty_cards \
  --email dev@example.com

# Get stores (for Pro accounts)
./mcp-server-yani/yani-query.sh yani_get_stores \
  --email merchant@example.com

# Get KYC status
./mcp-server-yani/yani-query.sh yani_get_kyc_status \
  --email dev@example.com

# Get crypto wallets (with external wallets)
./mcp-server-yani/yani-query.sh yani_get_crypto_wallets \
  --email dev@example.com

# Get referral data
./mcp-server-yani/yani-query.sh yani_get_referrals \
  --email dev@example.com

TTS tool

The TTS tool uses ElevenLabs to generate audio summaries. It requires --message:

TTS tool examplesbash

# Generate a voice summary
./mcp-server-yani/yani-query.sh yani_tts_summary \
  --message "Bonjour Johan, voici votre resume financier" \
  --context session_start

Global flags

--ttsRead the tool response aloud via ElevenLabs (works with all tools except yani_tts_summary)

--rawOutput raw JSON-RPC response instead of extracted text (useful for debugging)

Global flagsbash

# Read response aloud
./mcp-server-yani/yani-query.sh yani_get_balance \
  --email dev@example.com --tts

# Get raw JSON output for debugging
./mcp-server-yani/yani-query.sh --raw yani_financial_advice \
  --query "PEA ou assurance vie?"

Building a Custom Client

You can build your own MCP client in any language. Below are examples in TypeScript (using the official SDK) and Python (using the REST API).

TypeScript client (MCP SDK)

Use the official @modelcontextprotocol/sdk to connect via stdio transport:

custom-client.tstypescript

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

async function main() {
  // 1. Create a stdio transport pointing to the MCP server
  const transport = new StdioClientTransport({
    command: 'npx',
    args: ['tsx', 'mcp-server-yani/src/index.ts'],
    env: {
      ...process.env,
      DATABASE_URL: 'postgresql://user:pass@localhost:5432/yanipay',
    },
  });

  // 2. Create an MCP client and connect
  const client = new Client({
    name: 'my-custom-client',
    version: '1.0.0',
  });
  await client.connect(transport);

  // 3. Discover available tools
  const { tools } = await client.listTools();
  console.log('Available tools:', tools.map(t => t.name));
  // => ['yani_financial_advice', 'yani_get_balance', ...]

  // 4. Call an advisory tool
  const advice = await client.callTool({
    name: 'yani_financial_advice',
    arguments: {
      query: 'Best savings strategy for a DOM resident?',
      topic: 'epargne',
    },
  });
  console.log('Financial advice:', advice.content);

  // 5. Call a platform tool
  const balance = await client.callTool({
    name: 'yani_get_balance',
    arguments: {
      email: 'dev@example.com',
      wallet_type: 'ALL',
    },
  });
  console.log('Wallet balances:', balance.content);

  // 6. Read a resource
  const config = await client.readResource({
    uri: 'yani://config',
  });
  console.log('Server config:', config.contents);

  // 7. List available prompts
  const { prompts } = await client.listPrompts();
  console.log('Prompts:', prompts.map(p => p.name));

  // 8. Clean up
  await client.close();
}

main().catch(console.error);

Python client (REST API)

Use httpx or requests to call the REST API from Python. No MCP SDK required:

yani_client.pypython

import httpx

BASE_URL = "http://localhost:3101"

def main():
    client = httpx.Client(base_url=BASE_URL)

    # 1. Check health
    health = client.get("/health").json()
    print(f"Server: {health['server']} v{health['version']}")
    print(f"Tools: {health['tools']} ({health['advisory']} advisory + {health['platform']} platform)")

    # 2. Discover available tools
    tools = client.get("/tools").json()
    for tool in tools["tools"]:
        print(f"  - {tool['name']}: {tool['description'][:60]}...")

    # 3. Call an advisory tool
    advice = client.post("/tools/yani_financial_advice", json={
        "query": "Comment fonctionne le PEA pour un resident de La Reunion?",
        "context": "La Reunion",
        "topic": "epargne",
    }).json()
    print(f"\nFinancial advice:\n{advice['response'][:200]}...")

    # 4. Use universal query (auto-routing)
    result = client.post("/query", json={
        "query": "Quelles sont les etapes de verification KYC?",
    }).json()
    print(f"\nRouted to: {result['tool']}")
    print(f"Response: {result['response'][:200]}...")

    # 5. Call a platform tool
    balance = client.post("/tools/yani_get_balance", json={
        "email": "dev@example.com",
        "wallet_type": "ALL",
    }).json()
    print(f"\nBalance:\n{balance['response'][:200]}...")

    # 6. Get OpenAI-compatible schema
    schema = client.get("/openapi.json").json()
    print(f"\nOpenAI functions: {len(schema['functions'])} available")

    client.close()

if __name__ == "__main__":
    main()

Environment Variables

Configure the MCP server behavior with these environment variables:

Variable	Required	Default	Description
DATABASE_URL	Required	-	PostgreSQL connection string. Required for all platform tools.
PORT	Optional	3100 / 3101	HTTP server port. 3100 for HTTP/SSE, 3101 for REST API.
MCP_API_KEY	Optional	(none)	When set, enables Bearer token auth on the HTTP/SSE /mcp endpoint.
ELEVENLABS_API_KEY	Optional	(none)	Required for yani_tts_summary tool. ElevenLabs API key for voice synthesis.

.env (MCP server)bash

# Required
DATABASE_URL="postgresql://user:pass@localhost:5432/yanipay"

# Optional - HTTP/SSE server port (default: 3100)
PORT=3100

# Optional - Enable API key auth on HTTP/SSE transport
MCP_API_KEY="your-secret-api-key"

# Optional - ElevenLabs TTS for yani_tts_summary tool
ELEVENLABS_API_KEY="sk-your-elevenlabs-key"

Next Steps

MCP Overview

Architecture, transport comparison, and use case examples

Tools Reference

Complete documentation for all 37 tools with input schemas and response examples

Resources & Prompts

MCP resources for config, data models, and pre-built analysis prompts

Security & Auth

API key authentication, rate limiting, data sanitization, and audit logging