MCP for AI clients

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.

Connect with OAuth (recommended — no API key)

OAuth-capable MCP clients (Cursor, Claude Desktop, VS Code, and others) can connect without pasting a secret key. This is the simplest setup for fixing or testing MCP integrations in your IDE.

1. Add the hosted MCP server without headers:

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

2. Restart your MCP client. On first connect it receives a 401 with an OAuth discovery challenge, fetches https://mcp.lomi.africa/.well-known/oauth-protected-resource/mcp, and opens Connect with lomi. in your browser.
3. Sign in to the dashboard, choose your organization, and approve access (read-only by default).
4. The client receives a scoped token (lomi_oat_*) and can call MCP tools immediately.

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

More templates live in the repo: apps/mcp/examples/ (cursor-http-oauth.mcp.json, claude-desktop-http-oauth.mcp.json, plus API-key variants).

Connect with an API key (alternative)

Your LOMI_SECRET_KEY unlocks lomi.’s hosted MCP endpoint and scopes every tool call to your organization.

Connect with HTTP (Cursor, Claude Desktop)

Use lomi.’s hosted MCP server:

Example Cursor / Claude Desktop config:

{
  "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.

Connect with stdio (local)

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

{
  "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:

npx -y @lomi./mcp

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

Sandbox vs live

For HTTP MCP, tool calls use whichever API environment your LOMI_SECRET_KEY belongs to.

Tools, resources, and prompts

• lomi_search_tools: search the tool catalog when your client loads tools on demand.
• Resources: lomi://docs/getting-started, lomi://docs/errors, lomi://tools/index.
• Prompts: provision_merchant_from_zero (0-to-1 onboarding), onboard_merchant (post-signup integration), debug_failed_payment, setup_webhook.

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.

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

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

OAuth connect (self-service)

MCP clients that support MCP authorization can connect without pasting a provisioning 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 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:

Send x-lomi-partner-key: lomi_partner_* (or Authorization: Bearer lomi_partner_*). End users pass the returned lomi_prov_* to MCP or /provisioning/v1/*. 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.