# @moncashconnect/mcp

An open source, local (stdio) MCP server that exposes MonCashConnect's read only payment tools to AI coding assistants: Cursor, Claude Code, Codex, and any other MCP compatible client.

It runs on your machine, reads your MonCashConnect API key from an environment variable, and talks only to `api.moncashconnect.com`. It never writes to your live account and never moves money.

## Get a key

1. Open the MonCashConnect dashboard.
2. Go to **Read-only / AI keys**.
3. Create a key:
   - `sk_ro_proj_...` for live, read only access to your real account.
   - `sk_ro_test_...` for a sandbox account, safe for trying things out and for `create_test_payment`.

A full power `sk_proj_...` key will be rejected. This package only accepts read-only keys.

## Configure your AI tool

Paste this into your MCP client's config (Cursor, Claude Code, Codex, etc.), filling in your own key:

```json
{
  "mcpServers": {
    "moncashconnect": {
      "command": "npx",
      "args": ["-y", "@moncashconnect/mcp"],
      "env": { "MONCASHCONNECT_API_KEY": "sk_ro_test_your_key_here" }
    }
  }
}
```

The package is published on npm, so `npx -y @moncashconnect/mcp` works out of the box with the config above. No manual install needed.

## Local development / running from source

```bash
npm install
npm run build
```

Then point your MCP client's config at the built file instead of `npx`:

```json
{
  "mcpServers": {
    "moncashconnect": {
      "command": "node",
      "args": ["/absolute/path/to/moncashconnect-mcp/dist/index.js"],
      "env": { "MONCASHCONNECT_API_KEY": "sk_ro_test_your_key_here" }
    }
  }
}
```

## Tools

| Tool | Description |
| --- | --- |
| `get_payment` | Get one payment by its merchant reference: status, amount, and timestamps, with customer data masked. |
| `list_transactions` | List recent transactions, masked, with filters for status, type, and date range, paginated. |
| `get_balance` | Get the merchant's current available balance in HTG. |
| `debug_payment` | Explain why a payment is in its current state, with a sanitized diagnosis and suggestion. |
| `create_test_payment` | Create a sandbox test payment and return a payment URL and reference. Requires a sandbox key (`sk_ro_test_`); never moves real money. |
| `get_api_health` | Report overall MonCashConnect service status (operational or degraded) and environment. |
| `reveal_payment` | Reveal the unmasked customer details for exactly one payment. Requires a reason, and is audited and rate limited. |

## Safety

- Your key stays on your machine. It is read from the `MONCASHCONNECT_API_KEY` environment variable and is never logged.
- A read only key cannot move money and cannot write to your live account. Every tool in this package is a read operation.
- `reveal_payment` is audited and rate limited, and requires you to state a reason. Use it only when you genuinely need the unmasked detail.
- Use a sandbox key (`sk_ro_test_`) if you want to exercise `create_test_payment`; a live key (`sk_ro_proj_`) will refuse that tool.
- This package only ever contacts `api.moncashconnect.com`. It makes no other network calls and does not send your key or your data anywhere else.

## License

MIT