# 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 → Connecteurs**, puis **Développeurs → Clés API → Connecter MCP**.

Gmail, Agenda, Sheets, Drive, Slack et les autres applications que vous connectez pour l’assistant sont une liste à part. Voir [Applications connectées](/build/mcp/connectors).

## 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, sans OAuth). Appelez **`lomi_register_agent`** : le serveur résout une courte preuve de travail et la session MCP adopte une clé `lomi_prov_*` sandbox uniquement.

Les humains créent un compte sur `https://mcp.lomi.africa/mcp` (Connect with lomi. dans le navigateur). N’ajoutez pas `/mcp/guest` comme second connecteur pour y valider OAuth. L’invité n’annonce pas de serveur d’autorisation. OAuth sur cette URL casse la session MCP (`Unknown MCP session`).

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 avec une clé secrète collée, les appels utilisent l’environnement API associé à cette `LOMI_SECRET_KEY`.

Les connexions OAuth qui ont accordé **live et test** enregistrent **`lomi_environment`**. Les appels restent en live jusqu’à ce que vous passiez `environment` à `test` ou de nouveau à `live`. Omettez `environment` pour voir l’environnement actif et si les deux clés ont été accordées. Une connexion avec une seule clé n’enregistre pas cet outil.

## 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. Les descriptions des actions d’écriture listent les champs JSON du corps (requis d’abord, puis optionnels). Elles ne marquent pas quels champs du corps sont obligatoires.
* **`lomi_environment`**: enregistré seulement si OAuth a accordé live et test. Omettez `environment` pour voir `{ environment, live, test }`. Passez `live` ou `test` pour changer de session. Par défaut : live. Absent pour une clé API collée, une session invitée, ou un accord avec un seul environnement.
* **`lomi_events`**: bureau de réservation (`list`, `get`, `create`, `publish`, `scan`, `door_pin`, `add_type`, `invite`). Booking doit être connecté, sinon les écritures renvoient 403. `create` exige `header_Idempotency-Key`. Voir [Réservations d’événements](/build/accept/events).
* **`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`.
* Outils d’applications connectées avec une clé marchande qui n’est pas en lecture seule : **`lomi_mail`**, **`lomi_calendar`**, **`lomi_sms`**, **`lomi_domains`**, **`lomi_connectors`**, plus les outils de canal (`lomi_sheets`, `lomi_drive`, `lomi_telegram`, et les autres). Les écritures demandent encore une confirmation. Voir [Applications connectées](/build/mcp/connectors).
* 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.

### Network (`header_Lomi-Account`)

Les opérateurs [lomi. Network](/build/platform/network) approuvés utilisent la même clé secrète. Les en-têtes OpenAPI deviennent des arguments d’outil préfixés par `header_`. Le serveur transmet `header_Lomi-Account` comme `Lomi-Account: acct_...`.

| Modèle de paiement                | MCP                                                                                                                                                                                                                         |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Direct**                        | Passez `header_Lomi-Account` sur `lomi_checkout` `create`, `lomi_card_holds`, `lomi_customers`, `lomi_transactions`, `lomi_refunds`, `lomi_balance` et `lomi_payouts` quand la route REST correspondante accepte l’en-tête. |
| **Destination**                   | Omettez l’en-tête. Mettez `transfer_data.destination` dans le body de `lomi_checkout` create.                                                                                                                               |
| **Charges et transferts séparés** | Omettez l’en-tête. Créez le checkout sur le compte Opérateur, puis `lomi_transfers` `create` (aperçu, puis `confirmation_token`).                                                                                           |

`lomi_network` (`login_link`, `account_session`) est réservé à l’Opérateur : n’envoyez pas `header_Lomi-Account`. Les liens de paiement n’acceptent pas l’en-tête. `lomi_customers` `portal` le refuse : ouvrez le portail acheteur avec la clé du membre. Les charges Wave et MTN restent sur l’API REST.

Les écritures exigent toujours `header_Idempotency-Key` ou `idempotency_key`. Le Network live demande une approbation.

<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).