# MCP for AI clients
Source: https://docs.lomi.africa/build/mcp

Connect Cursor, Claude Desktop, or other MCP clients to the lomi. merchant API.

***

title: MCP for AI clients
description: Connect Cursor, Claude Desktop, or other MCP clients to the lomi. merchant API.
--------------------------------------------------------------------------------------------

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';

The **Model Context Protocol (MCP)** lets AI assistants (Cursor, Claude Desktop, custom agents) call the **lomi. merchant API** for you: create checkouts, list payments, debug webhooks, without writing every HTTP request by hand. Most teams use the hosted server at `https://mcp.lomi.africa` or local stdio with `npx @lomi./mcp`. Access is scoped to your organization, the same as your API key.

## Connect

Recommended: add the hosted MCP URL with **no API key**. OAuth-capable clients open **Connect with lomi.** in the browser, you sign in on the dashboard, and the client stores a scoped token (`lomi_oat_*`).

Two entry points, one product:

* **You have a lomi. account (or want one):** use the one-click buttons below. The consent page signs in or signs up, then returns to approve access.
* **Agent with no account yet:** connect `https://mcp.lomi.africa/mcp/guest`, call `lomi_register_agent`, then `lomi_provision`. Once `api_keys` returns a test key, the same session gains the merchant tools. See [Sandbox agent bootstrap](#sandbox-agent-bootstrap-no-key).

<McpOauthConnect />

Revoke a connected app from **Developers → API keys → Connect MCP → Connected apps**.

### Getting started

1. Click **Add to Cursor**, <a href={GROK_BOT_URL}>**Add to Grok Bot**</a>, <a href={buildClaudeOauthInstallUrl()}>**Add to Claude**</a>, or <a href={buildVscodeOauthInstallUrl()}>**Add to VS Code**</a> above (or paste the URL-only JSON below). OpenCode and Codex stay under the CLI sections.
2. On first connect the client receives a `401`, fetches `https://mcp.lomi.africa/.well-known/oauth-protected-resource/mcp`, and opens **Connect with lomi.**
3. Sign in to the dashboard, choose your organization, and approve access (read-only by default).
4. The client can call MCP tools immediately.

More templates live in the repo: [`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 API-key variants).

You can also start from the [dashboard](https://dashboard.lomi.africa): **Settings → Connectors**, then **Developers → API keys → Connect MCP**.

Gmail, Calendar, Sheets, Drive, Slack, and the other apps you connect for the assistant are a separate list. See [Connected apps](/build/mcp/connectors).

## Authentication

### OAuth (recommended)

OAuth-capable MCP clients (Cursor, Claude Desktop, VS Code, OpenCode, Codex, and others) connect without pasting a secret key.

1. Discover the resource server at `GET https://mcp.lomi.africa/.well-known/oauth-protected-resource/mcp` (also returned in the `WWW-Authenticate` challenge when connecting without credentials).
2. Register (optional DCR) at `POST https://api.lomi.africa/oauth/register`.
3. Open `GET https://api.lomi.africa/oauth/authorize` (PKCE + `resource` parameter).
4. Sign in on `https://dashboard.lomi.africa/connect/agent-connect` and approve.
5. Exchange the code at `POST https://api.lomi.africa/oauth/token`.
6. Connect to MCP with `Authorization: Bearer <access_token>` (`lomi_oat_*`).

The MCP server introspects the token and scopes every tool call to your organization.

### API key (`LOMI_SECRET_KEY`)

| Value                              | Header / env                                         | Where to get it                                                                                                                                            |
| ---------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Secret key (`LOMI_SECRET_KEY`)** | `x-lomi-api-key` (HTTP) or `LOMI_SECRET_KEY` (stdio) | [Dashboard](https://dashboard.lomi.africa) → **Developers → API keys**: any **secret** key (`lomi_sk_…`) or an MCP key (`lomi_mcp_…`) from **Connect MCP** |

Your **`LOMI_SECRET_KEY`** unlocks lomi.’s hosted MCP endpoint and scopes every tool call to your organization. Send it in `x-lomi-api-key` and leave `Authorization` empty.

## Hosted MCP (HTTP)

|                          | URL                                 |
| ------------------------ | ----------------------------------- |
| MCP endpoint             | `https://mcp.lomi.africa/mcp`       |
| Guest bootstrap (no key) | `https://mcp.lomi.africa/mcp/guest` |
| Health (optional)        | `https://mcp.lomi.africa/health`    |
| Ready check (optional)   | `https://mcp.lomi.africa/ready`     |

URL-only config (OAuth):

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

API-key config (fallback):

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

Replace `YOUR_LOMI_SECRET_KEY` with your real API key, then restart your MCP client.

### Sandbox agent bootstrap (no key)

If the client has no merchant key yet, connect `https://mcp.lomi.africa/mcp/guest` (no headers, no OAuth). Call **`lomi_register_agent`**: the server solves a short proof-of-work and this MCP session adopts a sandbox-only `lomi_prov_*` key.

Humans sign up on `https://mcp.lomi.africa/mcp` (Connect with lomi. in the browser). Do not add `/mcp/guest` as a second connector and approve OAuth on it. Guest does not advertise an authorization server. OAuth on that URL drops the MCP session (`Unknown MCP session`).

Then `lomi_provision action=create_account`, `upload_document`, `complete`, and `api_keys`. As soon as a `lomi_sk_test_*` key comes back, the guest session upgrades in place: the merchant tools (`lomi_checkout`, `lomi_customers`, `lomi_webhooks`, ...) are registered on the live session and the server sends `notifications/tools/list_changed`, so the client refreshes its tool list without reconnecting. Everything runs in TEST mode.

Live money still requires `lomi_provision action=request_live` and human approval at [dashboard.lomi.africa/connect/go-live](https://dashboard.lomi.africa/connect/go-live). Live keys are only shown in the dashboard, never over MCP.

### Discovery

* Hosted MCP: `https://mcp.lomi.africa/mcp`
* Server card: `https://mcp.lomi.africa/server-card`
* Public connect: [lomi.africa/connect](https://lomi.africa/connect)
* Smithery listing config lives in the repo (`apps/mcp/smithery.yaml`). Search: [smithery.ai/search?q=lomi.africa](https://smithery.ai/search?q=lomi.africa)
* ChatGPT: add the same MCP URL in developer mode. First-party app page: [lomi.africa/chatgpt](https://lomi.africa/chatgpt)
* Agent briefing: [lomi.africa/llms.txt](https://lomi.africa/llms.txt)

### Sandbox vs live

| Mode        | `LOMI_API_URL` (stdio)            | API keys                               |
| ----------- | --------------------------------- | -------------------------------------- |
| **Live**    | `https://api.lomi.africa`         | Live secret keys from the dashboard    |
| **Sandbox** | `https://sandbox.api.lomi.africa` | Sandbox secret keys from the dashboard |

For HTTP MCP with a pasted secret key, tool calls use whichever API environment that `LOMI_SECRET_KEY` belongs to.

OAuth connections that granted **both** live and test register **`lomi_environment`**. Calls use live until you pass `environment` as `test` or back to `live`. Omit `environment` to see which is active and whether both keys were granted. A connection with only one key does not register this tool.

## Clients

### Claude Code

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

On first use, Claude Code opens **Connect with lomi.** in the browser.

### 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
```

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

Install the lomi. plugin from your client's marketplace when it is available ([lomiafrica/agent-plugin](https://github.com/lomiafrica/agent-plugin)). You can always connect directly with the hosted MCP URL shown above; you do not need the plugin.

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

### Connect with stdio (local)

Runs the MCP server on your machine, no transport token needed. Good for local development.

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

Or run directly:

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

Set `LOMI_API_URL` to `https://sandbox.api.lomi.africa` when working against sandbox data.

## Tools

* Merchant tools are **resource tools** named `lomi_<resource>` with a required `action` (for example `lomi_customers` with `action=list`, `lomi_invoices` with `action=pdf`). Mechanical `lomi_post_*` / `lomi_get_*` aliases are not registered. Write-action descriptions list the JSON body fields for that action (required fields first, then optional). They do not mark which body fields are required.
* **`lomi_environment`**: registered only when OAuth granted both live and test. Omit `environment` to see `{ environment, live, test }`. Pass `live` or `test` to switch this session. Default is live. Not registered for a pasted API key, guest, or a grant with only one environment.
* **`lomi_events`**: booking desk (`list`, `get`, `create`, `publish`, `scan`, `door_pin`, `add_type`, `invite`). Booking must be connected or writes return 403. `create` needs `header_Idempotency-Key`. See [Event bookings](/build/accept/events).
* **`lomi_search_tools`**: search the tool catalog when your client loads tools on demand.
* **`lomi_register_agent`**: mint a sandbox provisioning key (guest or any session).
* **`lomi_support`**: file a complaint. Guest sessions send email (`action=file` with `email` + `message`). A merchant key opens a Settings → Support ticket (`list` / `get` / `close`). `action=status` returns the status page and `/ready`. Merchant-only: `action=export` (GDPR bundle for the current org) and `action=delete_account` (preview + `confirmation_token`).
* **`lomi_organization`**: `create` and `use` mint a secret for a new or existing org and adopt it on the session. Guest stays on `lomi_provision`.
* **`lomi_team`** / **`lomi_settings`**: members and invites; checkout and storefront settings (not payment sessions).
* **`lomi_logs`**: `type` is required (`api_request`, `api_error`, `webhook_delivery`, `activity`). Webhook debugging: `lomi_webhooks` deliveries/retry or `lomi_logs type=webhook_delivery`.
* Connected-app tools on a merchant key that is not read-only: **`lomi_mail`**, **`lomi_calendar`**, **`lomi_sms`**, **`lomi_domains`**, **`lomi_connectors`**, plus channel tools (`lomi_sheets`, `lomi_drive`, `lomi_telegram`, and the rest). Writes still ask you to confirm. See [Connected apps](/build/mcp/connectors).
* Provisioning: `lomi_provision` and `lomi_partners` (same `action` pattern).
* **Resources**: `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`.

Each MCP action below matches one REST operation. Card holds are `lomi_card_holds` (create, get, increment, capture, cancel). Wave, MTN, Switch, and `POST /usage/events` are not exposed over MCP.

### Network (`header_Lomi-Account`)

Approved [lomi. Network](/build/platform/network) Operators use the same secret key. OpenAPI header parameters become tool arguments prefixed with `header_`. The server forwards `header_Lomi-Account` as `Lomi-Account: acct_...`.

| Charge model                       | MCP                                                                                                                                                                                                                   |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Direct**                         | Pass `header_Lomi-Account` on `lomi_checkout` `create`, `lomi_card_holds`, `lomi_customers`, `lomi_transactions`, `lomi_refunds`, `lomi_balance`, and `lomi_payouts` when the matching REST route accepts the header. |
| **Destination**                    | Omit the header. Put `transfer_data.destination` in the `lomi_checkout` create body.                                                                                                                                  |
| **Separate charges and transfers** | Omit the header. Create the checkout on the Operator account, then `lomi_transfers` `create` (preview, then `confirmation_token`).                                                                                    |

`lomi_network` (`login_link`, `account_session`) is Operator-only: do not send `header_Lomi-Account`. Payment links do not accept the header. `lomi_customers` `portal` rejects it: launch the buyer portal with the member's own key. Wave and MTN direct charges stay on the REST API.

Writes still need `header_Idempotency-Key` or `idempotency_key`. Live Network requires approval.

<McpOperationIndex />

## Agent-driven onboarding (0 to 1)

Provisioning tools let an agent create a merchant account, upload KYC documents, complete onboarding, and retrieve **test** API keys before any merchant secret exists. MCP exposes this as **`lomi_provision`** with `action` (`create_account`, `upload_document`, `extract`, `complete`, `status`, `api_keys`, `request_live`, `live_status`).

**Human claim link.** `create_account` needs `email`, `full_name`, `terms_accepted_at`, and `terms_version`. Leave `password` out: the response includes a `claim_url` (`dashboard.lomi.africa/connect/claim?token=...`, valid 7 days, single use). Send this link to the human; they set their own password there and own the account. `status` reports `human_claimed` and re-issues `claim_url` until it flips to `true`. `request_live` returns `human_claimed` too: the human must claim before approving live mode.

| Value                                          | Header / env              | Purpose                                                                                    |
| ---------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------ |
| **Provisioning key (`LOMI_PROVISIONING_KEY`)** | `x-lomi-provisioning-key` | Bootstrap credential (`lomi_prov_*`) for `/provisioning/*`                                 |
| **Merchant secret (`LOMI_SECRET_KEY`)**        | `x-lomi-api-key`          | After onboarding completes, use test keys from `GET /provisioning/merchants/{id}/api-keys` |

Hosted HTTP example for a brand-new merchant (provisioning only until you have `lomi_sk_test_*`):

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

After onboarding, add `x-lomi-api-key` (or switch env to `LOMI_SECRET_KEY`) for payment and catalog tools. **TEST** mode works immediately; **LIVE** requires KYC clearance (AI for starter accounts, admin review for registered businesses).

Self-service OAuth onboarding uses the same **Connect with lomi.** flow. The MCP server introspects the token and provisions a scoped `lomi_prov_*` for your session. Self-service accounts are capped (verified email required, test-only, low daily merchant limits).

### Partner API (platform integrators)

Authorized platforms receive a **`lomi_partner_*`** management key from lomi admin. They mint per-end-user **`lomi_prov_*`** keys via MCP **`lomi_partners`** (`action=mint_key`, `list_keys`, `revoke_key`, `usage`) or the REST routes:

| Endpoint                                  | Purpose                                                   |
| ----------------------------------------- | --------------------------------------------------------- |
| `POST /partners/provisioning-keys`        | Mint a scoped provisioning key for an `external_user_ref` |
| `GET /partners/provisioning-keys`         | List keys                                                 |
| `DELETE /partners/provisioning-keys/{id}` | Revoke a key                                              |
| `GET /partners/usage`                     | Usage summary                                             |

Send `x-lomi-partner-key: lomi_partner_*` (or `Authorization: Bearer lomi_partner_*`). End users pass the returned `lomi_prov_*` to MCP or `/provisioning/*`. Monitor partners and audit events in **admin.lomi.africa → Provisioning**.

### Deploying your own MCP server

Most integrators use `https://mcp.lomi.africa` or local stdio. Deploying a separate MCP instance is for **lomi. engineering and operators** only. See [Maintaining CLI and MCP](/resources/contributing/maintaining-cli-mcp).
