# Xental MCP server

A [Model Context Protocol](https://modelcontextprotocol.io) server that lets any MCP-capable agent
(Claude Desktop, Claude Code, and others) operate a **[Xental](https://xental.online)** merchant
account through typed tools — provision virtual accounts, watch reconciled transactions, run payouts,
and drive the sandbox, all in natural language.

Instead of an agent scraping the dashboard, it talks to Xental over the same public API you use. This
is the "agent plane": your AI assistant becomes a first-class operator of your payments.

## Tools

| Tool | What it does |
|------|--------------|
| `get_agent_guide` | Reads `/.well-known/llms.txt` — auth, core flow, differentiators |
| `list_virtual_accounts` / `get_virtual_account` | List / fetch NUBANs with balance + reconciliation state |
| `create_virtual_account` | Provision a NUBAN for a customer (sandbox on test keys) |
| `delete_virtual_account` | Remove an account with no activity |
| `list_transactions` / `get_transaction` / `transactions_summary` | Reconciled inflows/outflows + totals |
| `list_banks` / `lookup_bank_account` | Payout bank list + name enquiry |
| `initiate_transfer` / `list_transfers` | Send a payout (idempotent) / list payouts |
| `simulate_deposit` | Sandbox: drive a real reconciliation with no bank movement |

All money is **integer kobo** (₦1 = 100 kobo). Money-moving calls are idempotent on a caller-supplied
reference.

## Install

```bash
git clone https://github.com/XENTAL-PayLibre/xental-mcp.git
cd xental-mcp
npm install
npm run build
```

This produces `build/index.js` — the executable server.

## Credentials

Create an API key in the Xental dashboard (**Settings → Developers**) and copy the **client id** and
**client secret** (the secret is shown once). Start with a **test-mode** key — it works immediately
and moves zero real money; live keys require approved KYC/KYB.

| Env var | Default | Notes |
|---------|---------|-------|
| `XENTAL_CLIENT_ID` | — | required |
| `XENTAL_CLIENT_SECRET` | — | required |
| `XENTAL_API_BASE` | `https://api.xental.online` | use `https://api.staging.xental.online` for sandbox |

## Use with Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "xental": {
      "command": "node",
      "args": ["/absolute/path/to/xental-mcp/build/index.js"],
      "env": {
        "XENTAL_API_BASE": "https://api.staging.xental.online",
        "XENTAL_CLIENT_ID": "your-client-id",
        "XENTAL_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

Restart Claude Desktop, then try:

> *"Create a test virtual account for Ada, simulate a ₦5,000 deposit, and show me the reconciliation."*

## Use with Claude Code

```bash
claude mcp add xental \
  --env XENTAL_API_BASE=https://api.staging.xental.online \
  --env XENTAL_CLIENT_ID=your-client-id \
  --env XENTAL_CLIENT_SECRET=your-client-secret \
  -- node /absolute/path/to/xental-mcp/build/index.js
```

## How auth works

The server exchanges your client credentials at `POST /api/v1/auth/token` for a short-lived bearer
token, caches it, and refreshes automatically on expiry or a `401`. Your secret never leaves the
machine the server runs on.

## Links

- Xental docs: https://xental.online/documentation
- MCP guide: https://xental.online/documentation/mcp
- Agent discovery (`llms.txt`): https://api.xental.online/.well-known/llms.txt

## License

MIT