# MCP pour clients IA
Source: https://docs.lomi.africa/build/mcp

Connectez Cursor, Claude Desktop ou tout client MCP à l’API marchande lomi..

***

title: MCP pour clients IA
description: Connectez Cursor, Claude Desktop ou tout client MCP à l’API marchande lomi..
-----------------------------------------------------------------------------------------

import { McpOauthConnect } from '@/components/docs/mcp-oauth-connect';
import { McpOperationIndex } from '@/components/docs/mcp-operation-index';
import {
  GROK_BOT_URL,
  buildClaudeOauthInstallUrl,
  buildVscodeOauthInstallUrl,
} from '@/lib/mcp/oauth-connect';

Le **Model Context Protocol (MCP)** permet à vos assistants IA (Cursor, Claude Desktop, agents maison) d’appeler **l’API marchande lomi.** : créer des checkouts, lister des paiements, déboguer des webhooks, sans écrire chaque requête HTTP à la main. La plupart des équipes utilisent le serveur hébergé `https://mcp.lomi.africa` ou le stdio local avec `npx @lomi./mcp`. L’accès est limité à votre organisation, comme avec votre clé API.

## Connexion

Recommandé : ajoutez l’URL MCP hébergée **sans clé API**. Les clients compatibles OAuth ouvrent **Connect with lomi.** dans le navigateur, vous vous connectez au tableau de bord, et le client stocke un jeton limité (`lomi_oat_*`).

Deux portes d’entrée, un seul produit :

* **Vous avez un compte lomi. (ou vous en voulez un) :** utilisez les boutons en un clic ci-dessous. La page de consentement vous connecte ou crée le compte, puis revient à l’approbation.
* **Agent sans compte :** connectez `https://mcp.lomi.africa/mcp/guest`, appelez `lomi_register_agent`, puis `lomi_provision`. Dès que `api_keys` renvoie une clé test, la même session obtient les outils marchands. Voir [Bootstrap agent sandbox](#bootstrap-agent-sandbox-sans-clé).

<McpOauthConnect />

Révoquez une application depuis **Développeurs → Clés API → Connecter MCP → Applications connectées**.

### Pour commencer

1. Cliquez sur **Ajouter à Cursor**, <a href={GROK_BOT_URL}>**Ajouter à Grok Bot**</a>, <a href={buildClaudeOauthInstallUrl()}>**Ajouter à Claude**</a> ou <a href={buildVscodeOauthInstallUrl()}>**Ajouter à VS Code**</a> ci-dessus (ou collez le JSON URL seule ci-dessous). OpenCode et Codex restent dans les sections CLI.
2. À la première connexion, le client reçoit un `401`, récupère `https://mcp.lomi.africa/.well-known/oauth-protected-resource/mcp`, puis ouvre **Connect with lomi.**
3. Connectez-vous au tableau de bord, choisissez votre organisation et approuvez l’accès (lecture seule par défaut).
4. Le client peut appeler les outils MCP tout de suite.

Modèles supplémentaires dans le dépôt : [`apps/mcp/examples/`](https://github.com/lomiafrica/lomi./tree/master/apps/mcp/examples) (`cursor-http-oauth.mcp.json`, `claude-desktop-http-oauth.mcp.json`, plus les variantes avec clé API).

Vous pouvez aussi commencer depuis le [tableau de bord](https://dashboard.lomi.africa) : **Paramètres → Intégrations → MCP**, puis **Développeurs → Clés API → Connecter MCP**.

## Authentification

### OAuth (recommandé)

Les clients MCP compatibles OAuth (Cursor, Claude Desktop, VS Code, OpenCode, Codex, etc.) se connectent sans coller de clé secrète.

1. Découverte : `GET https://mcp.lomi.africa/.well-known/oauth-protected-resource/mcp` (également renvoyé dans l’en-tête `WWW-Authenticate` lors d’une connexion sans identifiants).
2. Enregistrement (DCR optionnel) : `POST https://api.lomi.africa/oauth/register`.
3. Autorisation : `GET https://api.lomi.africa/oauth/authorize` (PKCE + paramètre `resource`).
4. Connexion sur `https://dashboard.lomi.africa/connect/agent-connect` et approbation.
5. Échange : `POST https://api.lomi.africa/oauth/token`.
6. Connexion MCP avec `Authorization: Bearer <access_token>` (`lomi_oat_*`).

Le serveur MCP introspecte le jeton et limite chaque appel d’outil à votre organisation.

### Clé API (`LOMI_SECRET_KEY`)

| Valeur                              | En-tête / variable d’env                             | Où l’obtenir                                                                                                                                                           |
| ----------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Clé secrète (`LOMI_SECRET_KEY`)** | `x-lomi-api-key` (HTTP) ou `LOMI_SECRET_KEY` (stdio) | [Tableau de bord](https://dashboard.lomi.africa) → **Développeurs → Clés API**: toute clé **secrète** (`lomi_sk_…`) ou clé MCP (`lomi_mcp_…`) depuis **Connecter MCP** |

Votre **`LOMI_SECRET_KEY`** ouvre l’accès au point de terminaison MCP hébergé par lomi. et limite chaque appel d’outil à votre organisation. Envoyez-la dans `x-lomi-api-key` et laissez `Authorization` vide.

## MCP hébergé (HTTP)

|                             | URL                                 |
| --------------------------- | ----------------------------------- |
| Point de terminaison MCP    | `https://mcp.lomi.africa/mcp`       |
| Bootstrap invité (sans clé) | `https://mcp.lomi.africa/mcp/guest` |
| Santé (optionnel)           | `https://mcp.lomi.africa/health`    |
| Prêt (optionnel)            | `https://mcp.lomi.africa/ready`     |

Config URL seule (OAuth) :

```json
{
  "mcpServers": {
    "lomi.": {
      "url": "https://mcp.lomi.africa/mcp"
    }
  }
}
```

Config avec clé API (repli) :

```json
{
  "mcpServers": {
    "lomi.": {
      "url": "https://mcp.lomi.africa/mcp",
      "headers": {
        "x-lomi-api-key": "YOUR_LOMI_SECRET_KEY"
      }
    }
  }
}
```

Remplacez `YOUR_LOMI_SECRET_KEY` par votre vraie clé API, puis redémarrez votre client MCP.

### Bootstrap agent sandbox (sans clé)

Si le client n’a pas encore de clé marchande, connectez `https://mcp.lomi.africa/mcp/guest` (sans en-têtes). Appelez **`lomi_register_agent`** : le serveur résout une courte preuve de travail et la session MCP adopte une clé `lomi_prov_*` sandbox uniquement.

Puis `lomi_provision action=create_account`, `upload_document`, `complete` et `api_keys`. Dès qu’une clé `lomi_sk_test_*` revient, la session invitée est mise à niveau sur place : les outils marchands (`lomi_checkout`, `lomi_customers`, `lomi_webhooks`, ...) sont enregistrés sur la session active et le serveur envoie `notifications/tools/list_changed` ; le client rafraîchit sa liste d’outils sans se reconnecter. Tout se passe en mode TEST.

L’argent live exige encore `lomi_provision action=request_live` et l’approbation humaine sur [dashboard.lomi.africa/connect/go-live](https://dashboard.lomi.africa/connect/go-live). Les clés live ne s’affichent que dans le tableau de bord, jamais via MCP.

### Découverte

* MCP hébergé : `https://mcp.lomi.africa/mcp`
* Carte serveur : `https://mcp.lomi.africa/server-card`
* Page de connexion : [lomi.africa/connect](https://lomi.africa/connect)
* La config Smithery est dans le dépôt (`apps/mcp/smithery.yaml`). Recherche : [smithery.ai/search?q=lomi.africa](https://smithery.ai/search?q=lomi.africa)
* ChatGPT : ajoutez la même URL MCP en mode développeur. Page de l'app : [lomi.africa/chatgpt](https://lomi.africa/chatgpt)
* Briefing agent : [lomi.africa/llms.txt](https://lomi.africa/llms.txt)

### Sandbox vs production

| Mode           | `LOMI_API_URL` (stdio)            | Clés API                                 |
| -------------- | --------------------------------- | ---------------------------------------- |
| **Production** | `https://api.lomi.africa`         | Clés secrètes live du tableau de bord    |
| **Sandbox**    | `https://sandbox.api.lomi.africa` | Clés secrètes sandbox du tableau de bord |

En HTTP MCP, les appels utilisent l’environnement API associé à votre `LOMI_SECRET_KEY`.

## Clients

### Claude Code

```bash
claude mcp add --transport http lomi https://mcp.lomi.africa/mcp
```

À la première utilisation, Claude Code ouvre **Connect with lomi.** dans le navigateur.

### OpenCode

```bash
opencode mcp add lomi --url https://mcp.lomi.africa/mcp
opencode mcp auth lomi
```

### Codex

```bash
codex mcp add lomi --url https://mcp.lomi.africa/mcp
codex mcp login lomi
```

### Plugin agent (Cursor, Codex, Copilot)

Installez le plugin lomi. depuis le marketplace de votre client quand il est disponible ([lomiafrica/agent-plugin](https://github.com/lomiafrica/agent-plugin)). Vous pouvez toujours vous connecter directement avec l’URL MCP ci-dessus ; le plugin n’est pas obligatoire.

```bash
codex plugin marketplace add lomiafrica/agent-plugin
codex plugin add lomi@lomi
```

### Connexion stdio (local)

Lance le serveur MCP sur votre machine, pas de jeton de transport. Idéal pour le développement local.

```json
{
  "mcpServers": {
    "lomi.": {
      "command": "npx",
      "args": ["-y", "@lomi./mcp"],
      "env": {
        "LOMI_SECRET_KEY": "YOUR_LOMI_SECRET_KEY",
        "LOMI_API_URL": "https://api.lomi.africa"
      }
    }
  }
}
```

Ou en direct :

```bash
npx -y @lomi./mcp
```

Utilisez `https://sandbox.api.lomi.africa` pour des données sandbox.

## Outils

* Les outils marchands sont des **outils ressource** nommés `lomi_<resource>` avec un `action` obligatoire (par exemple `lomi_customers` avec `action=list`, `lomi_invoices` avec `action=pdf`). Les alias mécaniques `lomi_post_*` / `lomi_get_*` ne sont pas enregistrés.
* **`lomi_search_tools`**: recherche dans le catalogue d’outils quand le client charge les outils à la demande.
* **`lomi_register_agent`**: émet une clé de provisioning sandbox (session invitée ou authentifiée).
* **`lomi_support`**: déposer une plainte. Session invitée : `action=file` avec `email` et `message`. Avec une clé marchande : ticket Paramètres → Assistance (`list` / `get` / `close`). `action=status` renvoie la page de statut et `/ready`. Clé marchande uniquement : `action=export` (bundle RGPD de l’org courante) et `action=delete_account` (aperçu + `confirmation_token`).
* **`lomi_organization`**: `create` et `use` émettent un secret pour un espace nouveau ou existant et l’adoptent sur la session. L’invité reste sur `lomi_provision`.
* **`lomi_team`** / **`lomi_settings`**: membres et invitations ; réglages checkout et vitrine (pas les sessions de paiement).
* **`lomi_logs`**: `type` est obligatoire (`api_request`, `api_error`, `webhook_delivery`, `activity`). Debug webhooks : `lomi_webhooks` deliveries/retry ou `lomi_logs type=webhook_delivery`. Marchand uniquement : `export` (bundle GDPR de l’org courante) et `delete_account` (aperçu + `confirmation_token`).
* **`lomi_organization`**: `create` / `use` émettent un secret et basculent la session MCP. L’invité reste sur `lomi_provision`.
* **`lomi_team`** et **`lomi_settings`**: invitations/rôles et réglages checkout/vitrine. `lomi_logs` exige `type`. Les livraisons webhook sont aussi sur `lomi_webhooks`.
* Provisioning : `lomi_provision` et `lomi_partners` (même schéma `action`).
* **Ressources**: `lomi://docs/getting-started`, `lomi://docs/authentication`, `lomi://docs/idempotency`, `lomi://docs/pagination`, `lomi://docs/webhooks`, `lomi://docs/money`, `lomi://docs/recipes`, `lomi://docs/finance`, `lomi://docs/errors`, `lomi://tools/index`.
* **Prompts**: `provision_merchant_from_zero`, `onboard_merchant`, `debug_failed_payment`, `setup_webhook`, `setup_network_operator`, `month_end_close`.

Chaque action MCP ci-dessous correspond à une opération de l’API. Les blocages carte sont `lomi_card_holds` (create, get, increment, capture, cancel). Wave, MTN, Switch et `POST /usage/events` ne sont pas exposés en MCP.

<McpOperationIndex />

## Onboarding piloté par agent (0 à 1)

Les outils de provisioning permettent à un agent de créer un compte marchand, déposer les documents KYC, finaliser l’onboarding et récupérer les clés API **test** avant toute clé secrète marchand. Le MCP expose cela via **`lomi_provision`** avec `action` (`create_account`, `upload_document`, `extract`, `complete`, `status`, `api_keys`, `request_live`, `live_status`).

**Lien de réclamation humain.** `create_account` attend `email`, `full_name`, `terms_accepted_at` et `terms_version`. N’envoyez pas de `password` : la réponse contient alors un `claim_url` (`dashboard.lomi.africa/connect/claim?token=...`, valable 7 jours, usage unique). Transmettez ce lien à l’humain ; il y définit son propre mot de passe et devient propriétaire du compte. `status` renvoie `human_claimed` et réémet `claim_url` tant qu’il vaut `false`. `request_live` renvoie aussi `human_claimed` : l’humain doit réclamer le compte avant d’approuver le mode live.

| Valeur                                            | En-tête / env             | Rôle                                                                                                 |
| ------------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Clé de provisioning (`LOMI_PROVISIONING_KEY`)** | `x-lomi-provisioning-key` | Identifiant bootstrap (`lomi_prov_*`) pour `/provisioning/*`                                         |
| **Secret marchand (`LOMI_SECRET_KEY`)**           | `x-lomi-api-key`          | Après l’onboarding, utilisez les clés test renvoyées par `GET /provisioning/merchants/{id}/api-keys` |

Exemple HTTP pour un nouveau marchand (provisioning seul tant que vous n’avez pas `lomi_sk_test_*`) :

```json
{
  "mcpServers": {
    "lomi.": {
      "url": "https://mcp.lomi.africa/mcp",
      "headers": {
        "x-lomi-provisioning-key": "YOUR_LOMI_PROVISIONING_KEY"
      }
    }
  }
}
```

Après l’onboarding, ajoutez `x-lomi-api-key` (ou passez `LOMI_SECRET_KEY` en env) pour les outils paiement et catalogue. Le mode **TEST** est disponible tout de suite ; le **LIVE** exige la validation KYC (IA pour les comptes starter, revue admin pour les entreprises enregistrées).

L’onboarding OAuth self-service utilise le même flux **Connect with lomi.** Le serveur MCP introspecte le jeton et attache un `lomi_prov_*` limité à la session. Comptes self-service plafonnés (e-mail vérifié, test uniquement).

### API Partenaire (intégrateurs plateforme)

Les plateformes autorisées reçoivent une clé de gestion **`lomi_partner_*`** (admin lomi). Elles émettent des clés **`lomi_prov_*`** par utilisateur via MCP **`lomi_partners`** (`action=mint_key`, `list_keys`, `revoke_key`, `usage`) ou `/partners/provisioning-keys` avec l’en-tête `x-lomi-partner-key`. Suivi dans **admin.lomi.africa → Provisioning**.

| Endpoint                                  | Rôle                                                        |
| ----------------------------------------- | ----------------------------------------------------------- |
| `POST /partners/provisioning-keys`        | Émettre une clé de provisioning pour un `external_user_ref` |
| `GET /partners/provisioning-keys`         | Lister les clés                                             |
| `DELETE /partners/provisioning-keys/{id}` | Révoquer une clé                                            |
| `GET /partners/usage`                     | Résumé d’usage                                              |

### Déployer votre propre serveur MCP

La plupart des intégrateurs utilisent `https://mcp.lomi.africa` ou le stdio local. Déployer une instance MCP séparée est réservé à **l’ingénierie et aux opérateurs lomi.** Voir [Maintenir la CLI et le MCP](/resources/contributing/maintaining-cli-mcp).