myfatoorah-mcp

# MyFatoorah MCP

An LLM-friendly [Model Context Protocol](https://modelcontextprotocol.io/) server for the [MyFatoorah API](https://docs.myfatoorah.com/docs/). It lets Claude, VS Code, Cursor, and other MCP hosts discover payment methods, create payment links, verify payments, inspect invoices, and manage refunds through focused tools.

> This is an independent community project, not an official MyFatoorah product. Test in the sandbox before using a live account.

For step-by-step host setup, Inspector testing, agent prompts, payment verification, refunds, and troubleshooting, see the [usage guide](docs/USAGE.md).

## Requirements

- Node.js 20 or newer
- A MyFatoorah API token with only the permissions required by the tools you use

## Setup

```sh
npm install
cp .env.example .env
npm run build
```

Set `MYFATOORAH_API_TOKEN` in the MCP host's environment. The server does not automatically load `.env`; the VS Code debug configuration does.

### Environment variables

| Variable                 | Required                  | Default         | Description                                                        |
| ------------------------ | ------------------------- | --------------- | ------------------------------------------------------------------ |
| `MYFATOORAH_API_TOKEN`   | Yes, when calling the API | —               | Bearer token. Never expose it to an agent prompt.                  |
| `MYFATOORAH_ENVIRONMENT` | No                        | `test`          | `test`, `kuwait`, `uae`, `saudi_arabia`, `qatar`, or `egypt`       |
| `MYFATOORAH_BASE_URL`    | No                        | Environment URL | HTTPS override for a supported MyFatoorah deployment or test proxy |
| `MYFATOORAH_TIMEOUT_MS`  | No                        | `30000`         | Request timeout from 1 to 300000 ms                                |

Kuwait also covers the shared Bahrain, Jordan, and Oman API origin. Multi-country accounts use a separate token for each country.

## Connect an MCP host

Use an absolute path in host configurations. Replace `/absolute/path/to/myfatoorah-mcp` and the token placeholder locally.

### Claude Desktop

Add this server to Claude Desktop's MCP configuration:

```json
{
  "mcpServers": {
    "myfatoorah": {
      "command": "node",
      "args": ["/absolute/path/to/myfatoorah-mcp/dist/index.js"],
      "env": {
        "MYFATOORAH_API_TOKEN": "YOUR_TOKEN",
        "MYFATOORAH_ENVIRONMENT": "test"
      }
    }
  }
}
```

Restart Claude Desktop after saving the configuration.

### Claude Code

Project-scoped configuration can use `.mcp.json` (keep it uncommitted if it contains a token):

```json
{
  "mcpServers": {
    "myfatoorah": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/myfatoorah-mcp/dist/index.js"],
      "env": {
        "MYFATOORAH_API_TOKEN": "YOUR_TOKEN",
        "MYFATOORAH_ENVIRONMENT": "test"
      }
    }
  }
}
```

### VS Code / GitHub Copilot

The included `.vscode/mcp.json` launches the built server and securely prompts for a token. Build once, open the MCP servers view, then start `myfatoorah`. The token is not stored in the repository.

### Cursor and generic stdio hosts

Use the same `command`, `args`, and `env` values as the Claude Desktop example. MCP protocol messages use stdin/stdout; server diagnostics must use stderr.

After publishing to npm, hosts can instead launch it with `npx -y myfatoorah-mcp`.

## Tools

| Tool                             | Effect       | Purpose                                                                                     |
| -------------------------------- | ------------ | ------------------------------------------------------------------------------------------- |
| `myfatoorah_get_payment_methods` | Read-only    | Lists enabled methods and their `ApiName` values                                            |
| `myfatoorah_create_payment`      | Creates data | Creates a hosted checkout or invoice link with `POST /v3/payments`                          |
| `myfatoorah_get_payment`         | Read-only    | Gets authoritative payment details by PaymentId                                             |
| `myfatoorah_get_invoice`         | Read-only    | Gets an invoice by InvoiceId or external identifier                                         |
| `myfatoorah_create_refund`       | Destructive  | Creates a full or partial refund; requires `confirm: true`                                  |
| `myfatoorah_get_refund`          | Read-only    | Gets refund details by RefundId                                                             |
| `myfatoorah_api_request`         | Varies       | Restricted escape hatch for relative `/v2/` or `/v3/` paths; mutations require confirmation |

The server also exposes:

- Resource `myfatoorah://configuration`: environment, base URL, timeout, and whether a token is configured—never the token itself.
- Prompt `create-payment-safely`: a reusable guided payment-link workflow.

Successful tools return a concise text summary plus machine-readable `structuredContent` containing the MyFatoorah response.

## Safe payment workflow

1. Read `myfatoorah://configuration` and confirm test versus live.
2. If selecting a gateway, call `myfatoorah_get_payment_methods` and use its `ApiName`.
3. Confirm amount, currency, customer, notification method, and callback URL.
4. Call `myfatoorah_create_payment` and give the customer its `PaymentURL`.
5. After callback, call `myfatoorah_get_payment` with the returned PaymentId. A redirect is not proof of payment; require invoice status `PAID` and transaction status `SUCCESS`.

Refunds move money in live mode. Obtain explicit user approval for the exact PaymentId and amount before passing `confirm: true`.

## Development

```sh
npm run format
npm run lint
npm run typecheck
npm test
npm run build
npm run inspect
```

`npm run inspect` starts the official MCP Inspector against the compiled stdio server. VS Code also includes build/test tasks and a debug configuration.

Tests mock every MyFatoorah request; they do not make network calls or require a token.

## Security

- Use a least-privilege MyFatoorah API key and rotate it regularly.
- Put credentials in the host environment or a secret manager, never source control or model context.
- The generic request tool rejects absolute URLs, protocol-relative URLs, traversal, and paths outside `/v2/` and `/v3/` to prevent credential exfiltration.
- API errors and Bearer values are redacted before reaching the model.
- Prefer idempotency keys for supported mutations and stable order identifiers.
- Do not expose this stdio process as an unauthenticated network service.
- Direct card handling is intentionally not modeled as a focused tool; it requires PCI compliance.

## API scope and references

The focused tools use MyFatoorah's documented v3 routes as of August 2026:

- `GET /v3/payment-methods`
- `POST /v3/payments`
- `GET /v3/payments/{paymentId}`
- `GET /v3/invoices/{invoiceId}`
- `GET /v3/invoices/externalIdentifier/{externalIdentifier}`
- `POST /v3/refunds`
- `GET /v3/refunds/{refundId}`

References:

- [MyFatoorah API key and regional URLs](https://docs.myfatoorah.com/docs/api-key)
- [MCP TypeScript SDK v2](https://ts.sdk.modelcontextprotocol.io/v2/)
- [Model Context Protocol specification](https://modelcontextprotocol.io/specification/latest)

## License

MIT