POST /api/v1/gateway/mcp

MCP endpoint

The same gateway as tools for AI agents, over the Model Context Protocol: one JSON-RPC 2.0 message per POST (methods `initialize`, `ping`, `tools/list`, `tools/call`; notifications such as `notifications/initialized` answer `202` with no body). Authenticate with your merchant API key exactly as for the REST gateway — `Authorization: Bearer <key_id>:<secret>` or the `X-Malaleem-Key` / `X-Malaleem-Secret` headers. Every tool sees only your sessions and transfers in your key's mode (a test key never touches live ones); another merchant's is "not found". Rate limited to 60 requests a minute per API key (`429` with `Retry-After`). Protocol errors are JSON-RPC errors: -32700 parse error, -32600 invalid request, -32601 method not found, -32602 invalid params or unknown tool. A tool that runs but cannot do what was asked (missing argument, unknown session, nothing left to refund) answers a normal result with `isError: true` and a plain message.

Parameters

jsonrpc string · required

Always "2.0".

id integer | string · required

Echoed on the reply. Omit it to send a notification (answered 202, no body).

method string · required

initialize | ping | tools/list | tools/call.

params object

For tools/call: `{name, arguments}` — the tools are listed below.

curl https://malaleem.com/api/v1/gateway/mcp \
  -H "Authorization: Bearer {key_id}:{secret}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"create_payment_link","arguments":
         {"idempotency_key":"order-1042","amount":4999,"currency":"USD","reference":"1042"}}}'