@monnify/mcp-server 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (192) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +563 -0
  3. package/build/auth/tokenManager.d.ts +11 -0
  4. package/build/auth/tokenManager.d.ts.map +1 -0
  5. package/build/auth/tokenManager.js +62 -0
  6. package/build/auth/tokenManager.js.map +1 -0
  7. package/build/cli.d.ts +3 -0
  8. package/build/cli.d.ts.map +1 -0
  9. package/build/cli.js +39 -0
  10. package/build/cli.js.map +1 -0
  11. package/build/client/monnifyClient.d.ts +7 -0
  12. package/build/client/monnifyClient.d.ts.map +1 -0
  13. package/build/client/monnifyClient.js +119 -0
  14. package/build/client/monnifyClient.js.map +1 -0
  15. package/build/config/env.d.ts +47 -0
  16. package/build/config/env.d.ts.map +1 -0
  17. package/build/config/env.js +39 -0
  18. package/build/config/env.js.map +1 -0
  19. package/build/index.d.ts +36 -0
  20. package/build/index.d.ts.map +1 -0
  21. package/build/index.js +84 -0
  22. package/build/index.js.map +1 -0
  23. package/build/schemas/compat.d.ts +24 -0
  24. package/build/schemas/compat.d.ts.map +1 -0
  25. package/build/schemas/compat.js +20 -0
  26. package/build/schemas/compat.js.map +1 -0
  27. package/build/schemas/extended/collections.d.ts +439 -0
  28. package/build/schemas/extended/collections.d.ts.map +1 -0
  29. package/build/schemas/extended/collections.js +403 -0
  30. package/build/schemas/extended/collections.js.map +1 -0
  31. package/build/schemas/extended/directDebit.d.ts +123 -0
  32. package/build/schemas/extended/directDebit.d.ts.map +1 -0
  33. package/build/schemas/extended/directDebit.js +121 -0
  34. package/build/schemas/extended/directDebit.js.map +1 -0
  35. package/build/schemas/extended/verification.d.ts +55 -0
  36. package/build/schemas/extended/verification.d.ts.map +1 -0
  37. package/build/schemas/extended/verification.js +51 -0
  38. package/build/schemas/extended/verification.js.map +1 -0
  39. package/build/schemas/generated.d.ts +4 -0
  40. package/build/schemas/generated.d.ts.map +1 -0
  41. package/build/schemas/generated.js +2603 -0
  42. package/build/schemas/generated.js.map +1 -0
  43. package/build/security/guards.d.ts +5 -0
  44. package/build/security/guards.d.ts.map +1 -0
  45. package/build/security/guards.js +43 -0
  46. package/build/security/guards.js.map +1 -0
  47. package/build/security/sanitiser.d.ts +46 -0
  48. package/build/security/sanitiser.d.ts.map +1 -0
  49. package/build/security/sanitiser.js +269 -0
  50. package/build/security/sanitiser.js.map +1 -0
  51. package/build/tools/collections/authoriseCard3ds.d.ts +7 -0
  52. package/build/tools/collections/authoriseCard3ds.d.ts.map +1 -0
  53. package/build/tools/collections/authoriseCard3ds.js +63 -0
  54. package/build/tools/collections/authoriseCard3ds.js.map +1 -0
  55. package/build/tools/collections/authoriseCardOtp.d.ts +7 -0
  56. package/build/tools/collections/authoriseCardOtp.d.ts.map +1 -0
  57. package/build/tools/collections/authoriseCardOtp.js +55 -0
  58. package/build/tools/collections/authoriseCardOtp.js.map +1 -0
  59. package/build/tools/collections/chargeCard.d.ts +7 -0
  60. package/build/tools/collections/chargeCard.d.ts.map +1 -0
  61. package/build/tools/collections/chargeCard.js +59 -0
  62. package/build/tools/collections/chargeCard.js.map +1 -0
  63. package/build/tools/collections/chargeCardToken.d.ts +7 -0
  64. package/build/tools/collections/chargeCardToken.d.ts.map +1 -0
  65. package/build/tools/collections/chargeCardToken.js +68 -0
  66. package/build/tools/collections/chargeCardToken.js.map +1 -0
  67. package/build/tools/collections/createInvoice.d.ts +7 -0
  68. package/build/tools/collections/createInvoice.d.ts.map +1 -0
  69. package/build/tools/collections/createInvoice.js +57 -0
  70. package/build/tools/collections/createInvoice.js.map +1 -0
  71. package/build/tools/collections/deallocateReservedAccount.d.ts +14 -0
  72. package/build/tools/collections/deallocateReservedAccount.d.ts.map +1 -0
  73. package/build/tools/collections/deallocateReservedAccount.js +55 -0
  74. package/build/tools/collections/deallocateReservedAccount.js.map +1 -0
  75. package/build/tools/collections/getAllTransactions.d.ts +47 -0
  76. package/build/tools/collections/getAllTransactions.d.ts.map +1 -0
  77. package/build/tools/collections/getAllTransactions.js +140 -0
  78. package/build/tools/collections/getAllTransactions.js.map +1 -0
  79. package/build/tools/collections/getReservedAccount.d.ts +14 -0
  80. package/build/tools/collections/getReservedAccount.d.ts.map +1 -0
  81. package/build/tools/collections/getReservedAccount.js +55 -0
  82. package/build/tools/collections/getReservedAccount.js.map +1 -0
  83. package/build/tools/collections/getReservedAccountTransactions.d.ts +20 -0
  84. package/build/tools/collections/getReservedAccountTransactions.d.ts.map +1 -0
  85. package/build/tools/collections/getReservedAccountTransactions.js +86 -0
  86. package/build/tools/collections/getReservedAccountTransactions.js.map +1 -0
  87. package/build/tools/collections/getTransactionDetails.d.ts +14 -0
  88. package/build/tools/collections/getTransactionDetails.d.ts.map +1 -0
  89. package/build/tools/collections/getTransactionDetails.js +60 -0
  90. package/build/tools/collections/getTransactionDetails.js.map +1 -0
  91. package/build/tools/collections/getTransactionStatus.d.ts +7 -0
  92. package/build/tools/collections/getTransactionStatus.d.ts.map +1 -0
  93. package/build/tools/collections/getTransactionStatus.js +58 -0
  94. package/build/tools/collections/getTransactionStatus.js.map +1 -0
  95. package/build/tools/collections/initiatePayment.d.ts +7 -0
  96. package/build/tools/collections/initiatePayment.d.ts.map +1 -0
  97. package/build/tools/collections/initiatePayment.js +63 -0
  98. package/build/tools/collections/initiatePayment.js.map +1 -0
  99. package/build/tools/collections/payWithBankTransfer.d.ts +7 -0
  100. package/build/tools/collections/payWithBankTransfer.d.ts.map +1 -0
  101. package/build/tools/collections/payWithBankTransfer.js +55 -0
  102. package/build/tools/collections/payWithBankTransfer.js.map +1 -0
  103. package/build/tools/collections/processRefund.d.ts +7 -0
  104. package/build/tools/collections/processRefund.d.ts.map +1 -0
  105. package/build/tools/collections/processRefund.js +55 -0
  106. package/build/tools/collections/processRefund.js.map +1 -0
  107. package/build/tools/collections/reserveAccount.d.ts +7 -0
  108. package/build/tools/collections/reserveAccount.d.ts.map +1 -0
  109. package/build/tools/collections/reserveAccount.js +57 -0
  110. package/build/tools/collections/reserveAccount.js.map +1 -0
  111. package/build/tools/directDebit/cancelMandate.d.ts +7 -0
  112. package/build/tools/directDebit/cancelMandate.d.ts.map +1 -0
  113. package/build/tools/directDebit/cancelMandate.js +55 -0
  114. package/build/tools/directDebit/cancelMandate.js.map +1 -0
  115. package/build/tools/directDebit/createMandate.d.ts +7 -0
  116. package/build/tools/directDebit/createMandate.d.ts.map +1 -0
  117. package/build/tools/directDebit/createMandate.js +55 -0
  118. package/build/tools/directDebit/createMandate.js.map +1 -0
  119. package/build/tools/directDebit/debitMandate.d.ts +7 -0
  120. package/build/tools/directDebit/debitMandate.d.ts.map +1 -0
  121. package/build/tools/directDebit/debitMandate.js +55 -0
  122. package/build/tools/directDebit/debitMandate.js.map +1 -0
  123. package/build/tools/directDebit/getMandateDebitStatus.d.ts +7 -0
  124. package/build/tools/directDebit/getMandateDebitStatus.d.ts.map +1 -0
  125. package/build/tools/directDebit/getMandateDebitStatus.js +55 -0
  126. package/build/tools/directDebit/getMandateDebitStatus.js.map +1 -0
  127. package/build/tools/directDebit/getMandateStatus.d.ts +7 -0
  128. package/build/tools/directDebit/getMandateStatus.d.ts.map +1 -0
  129. package/build/tools/directDebit/getMandateStatus.js +55 -0
  130. package/build/tools/directDebit/getMandateStatus.js.map +1 -0
  131. package/build/tools/registry.d.ts +11 -0
  132. package/build/tools/registry.d.ts.map +1 -0
  133. package/build/tools/registry.js +15 -0
  134. package/build/tools/registry.js.map +1 -0
  135. package/build/tools/utilities/getSupportedBanks.d.ts +8 -0
  136. package/build/tools/utilities/getSupportedBanks.d.ts.map +1 -0
  137. package/build/tools/utilities/getSupportedBanks.js +47 -0
  138. package/build/tools/utilities/getSupportedBanks.js.map +1 -0
  139. package/build/tools/utilities/getTransactionList.d.ts +47 -0
  140. package/build/tools/utilities/getTransactionList.d.ts.map +1 -0
  141. package/build/tools/utilities/getTransactionList.js +136 -0
  142. package/build/tools/utilities/getTransactionList.js.map +1 -0
  143. package/build/tools/verification/verifyBankAccount.d.ts +7 -0
  144. package/build/tools/verification/verifyBankAccount.d.ts.map +1 -0
  145. package/build/tools/verification/verifyBankAccount.js +58 -0
  146. package/build/tools/verification/verifyBankAccount.js.map +1 -0
  147. package/build/tools/verification/verifyBvn.d.ts +7 -0
  148. package/build/tools/verification/verifyBvn.d.ts.map +1 -0
  149. package/build/tools/verification/verifyBvn.js +55 -0
  150. package/build/tools/verification/verifyBvn.js.map +1 -0
  151. package/build/tools/verification/verifyBvnInfo.d.ts +7 -0
  152. package/build/tools/verification/verifyBvnInfo.d.ts.map +1 -0
  153. package/build/tools/verification/verifyBvnInfo.js +55 -0
  154. package/build/tools/verification/verifyBvnInfo.js.map +1 -0
  155. package/build/tools/verification/verifyNin.d.ts +7 -0
  156. package/build/tools/verification/verifyNin.d.ts.map +1 -0
  157. package/build/tools/verification/verifyNin.js +55 -0
  158. package/build/tools/verification/verifyNin.js.map +1 -0
  159. package/build/transport/http.d.ts +3 -0
  160. package/build/transport/http.d.ts.map +1 -0
  161. package/build/transport/http.js +71 -0
  162. package/build/transport/http.js.map +1 -0
  163. package/build/transport/stdio.d.ts +3 -0
  164. package/build/transport/stdio.d.ts.map +1 -0
  165. package/build/transport/stdio.js +8 -0
  166. package/build/transport/stdio.js.map +1 -0
  167. package/build/types/mcp.d.ts +11 -0
  168. package/build/types/mcp.d.ts.map +1 -0
  169. package/build/types/mcp.js +7 -0
  170. package/build/types/mcp.js.map +1 -0
  171. package/build/utils/clientContext.d.ts +7 -0
  172. package/build/utils/clientContext.d.ts.map +1 -0
  173. package/build/utils/clientContext.js +24 -0
  174. package/build/utils/clientContext.js.map +1 -0
  175. package/build/utils/errors.d.ts +21 -0
  176. package/build/utils/errors.d.ts.map +1 -0
  177. package/build/utils/errors.js +45 -0
  178. package/build/utils/errors.js.map +1 -0
  179. package/build/utils/format.d.ts +34 -0
  180. package/build/utils/format.d.ts.map +1 -0
  181. package/build/utils/format.js +362 -0
  182. package/build/utils/format.js.map +1 -0
  183. package/build/utils/formatters.d.ts +4 -0
  184. package/build/utils/formatters.d.ts.map +1 -0
  185. package/build/utils/formatters.js +26 -0
  186. package/build/utils/formatters.js.map +1 -0
  187. package/build/utils/logger.d.ts +3 -0
  188. package/build/utils/logger.d.ts.map +1 -0
  189. package/build/utils/logger.js +30 -0
  190. package/build/utils/logger.js.map +1 -0
  191. package/openapi/monnify.yaml +9295 -0
  192. package/package.json +55 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Monnify Payment Gateway
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,563 @@
1
+ # @monnify/mcp-server
2
+
3
+ [![CI](https://github.com/monnify/monnify-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/monnify/monnify-mcp-server/actions/workflows/ci.yml)
4
+ [![npm version](https://img.shields.io/npm/v/@monnify/mcp-server.svg)](https://www.npmjs.com/package/@monnify/mcp-server)
5
+
6
+ Give your AI assistant the ability to accept payments, verify identities, manage virtual accounts, and query transactions — all through [Monnify](https://monnify.com).
7
+
8
+ This is an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server. Once connected, your AI client can talk directly to the Monnify API using plain language — no custom integration code required.
9
+
10
+ ---
11
+
12
+ ## What you can do once it's connected
13
+
14
+ **Payment collection**
15
+ > *"Initiate a payment of ₦15,000 for invoice #INV-2024-007 and send me the checkout link"*
16
+ > *"Create a dedicated virtual account for customer cust_089 so they can pay anytime by bank transfer"*
17
+ > *"Get me the status of transaction TRX-20240601-001"*
18
+ > *"Show me all failed transactions from last week"*
19
+
20
+ **Identity verification**
21
+ > *"Verify that account 0123456789 belongs to John Doe at GTBank"*
22
+ > *"Check BVN 22345678901 — does the name and date of birth match?"*
23
+ > *"Verify NIN 12345678901 for a customer named Amaka Obi"*
24
+
25
+ **Account management**
26
+ > *"What transactions came into reserved account ACCT-REF-001 this month?"*
27
+ > *"Deallocate the virtual account for the customer who churned last quarter"*
28
+ > *"Create a payment invoice for ₦50,000 that expires in 48 hours"*
29
+
30
+ **Engineering / integrations**
31
+ > *"List all banks and their codes so I can populate a dropdown"*
32
+ > *"Get the full details of transaction REF-XYZ for a support ticket"*
33
+ > *"Process a partial refund of ₦2,500 on transaction TRX-20240601-009"*
34
+
35
+ ---
36
+
37
+ ## Prerequisites
38
+
39
+ - Node.js 20 or later
40
+ - A [Monnify account](https://app.monnify.com/login) with API access enabled
41
+ - Your **API Key**, **Secret Key**, and **Contract Code** from the Monnify Dashboard → Developer → API Keys & Contracts
42
+
43
+ ---
44
+
45
+ ## Quick start (no install needed)
46
+
47
+ ```bash
48
+ npx -y @monnify/mcp-server \
49
+ --apiKey=YOUR_API_KEY \
50
+ --secretKey=YOUR_SECRET_KEY \
51
+ --contractCode=YOUR_CONTRACT_CODE \
52
+ --env=sandbox
53
+ ```
54
+
55
+ Switch `--env=sandbox` to `--env=production` when you're ready to go live.
56
+
57
+ ---
58
+
59
+ ## Connect to your AI client
60
+
61
+ The server speaks the MCP stdio protocol, which is supported by all major AI tools. Pick yours below.
62
+
63
+ ---
64
+
65
+ ### Claude Desktop
66
+
67
+ **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
68
+ **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
69
+
70
+ ```json
71
+ {
72
+ "mcpServers": {
73
+ "monnify": {
74
+ "command": "npx",
75
+ "args": [
76
+ "-y",
77
+ "@monnify/mcp-server",
78
+ "--apiKey=YOUR_API_KEY",
79
+ "--secretKey=YOUR_SECRET_KEY",
80
+ "--contractCode=YOUR_CONTRACT_CODE",
81
+ "--env=sandbox"
82
+ ]
83
+ }
84
+ }
85
+ }
86
+ ```
87
+
88
+ Restart Claude Desktop after saving. You will see "monnify" appear in the tools panel.
89
+
90
+ ---
91
+
92
+ ### Claude Code (CLI)
93
+
94
+ **Project-level** — add to `.claude/mcp.json` in your repo (checked in, shared with your team):
95
+
96
+ ```json
97
+ {
98
+ "servers": {
99
+ "monnify": {
100
+ "type": "stdio",
101
+ "command": "npx",
102
+ "args": [
103
+ "-y",
104
+ "@monnify/mcp-server",
105
+ "--apiKey=YOUR_API_KEY",
106
+ "--secretKey=YOUR_SECRET_KEY",
107
+ "--contractCode=YOUR_CONTRACT_CODE",
108
+ "--env=sandbox"
109
+ ]
110
+ }
111
+ }
112
+ }
113
+ ```
114
+
115
+ **Global** — add to `~/.claude/claude_desktop_config.json` so it's available in every Claude Code session:
116
+
117
+ ```bash
118
+ claude mcp add monnify \
119
+ -- npx -y @monnify/mcp-server \
120
+ --apiKey=YOUR_API_KEY \
121
+ --secretKey=YOUR_SECRET_KEY \
122
+ --contractCode=YOUR_CONTRACT_CODE \
123
+ --env=sandbox
124
+ ```
125
+
126
+ Verify it loaded:
127
+ ```bash
128
+ claude mcp list
129
+ ```
130
+
131
+ ---
132
+
133
+ ### ChatGPT Desktop (OpenAI)
134
+
135
+ **Mac:** `~/Library/Application Support/ChatGPT/mcp.json`
136
+ **Windows:** `%APPDATA%\ChatGPT\mcp.json`
137
+
138
+ ```json
139
+ {
140
+ "mcpServers": {
141
+ "monnify": {
142
+ "command": "npx",
143
+ "args": [
144
+ "-y",
145
+ "@monnify/mcp-server",
146
+ "--apiKey=YOUR_API_KEY",
147
+ "--secretKey=YOUR_SECRET_KEY",
148
+ "--contractCode=YOUR_CONTRACT_CODE",
149
+ "--env=sandbox"
150
+ ]
151
+ }
152
+ }
153
+ }
154
+ ```
155
+
156
+ Restart ChatGPT Desktop. MCP tools will appear in the tool-use panel when you start a new conversation.
157
+
158
+ ---
159
+
160
+ ### Gemini CLI
161
+
162
+ Add to `~/.gemini/settings.json`:
163
+
164
+ ```json
165
+ {
166
+ "mcpServers": {
167
+ "monnify": {
168
+ "command": "npx",
169
+ "args": [
170
+ "-y",
171
+ "@monnify/mcp-server",
172
+ "--apiKey=YOUR_API_KEY",
173
+ "--secretKey=YOUR_SECRET_KEY",
174
+ "--contractCode=YOUR_CONTRACT_CODE",
175
+ "--env=sandbox"
176
+ ]
177
+ }
178
+ }
179
+ }
180
+ ```
181
+
182
+ Run `gemini` in your terminal — type `@monnify` to confirm the server is available.
183
+
184
+ ---
185
+
186
+ ### Cursor
187
+
188
+ Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in your project root:
189
+
190
+ ```json
191
+ {
192
+ "mcpServers": {
193
+ "monnify": {
194
+ "command": "npx",
195
+ "args": [
196
+ "-y",
197
+ "@monnify/mcp-server",
198
+ "--apiKey=YOUR_API_KEY",
199
+ "--secretKey=YOUR_SECRET_KEY",
200
+ "--contractCode=YOUR_CONTRACT_CODE",
201
+ "--env=sandbox"
202
+ ]
203
+ }
204
+ }
205
+ }
206
+ ```
207
+
208
+ Open Cursor Settings → MCP to confirm the server shows as active.
209
+
210
+ ---
211
+
212
+ ### VS Code + GitHub Copilot
213
+
214
+ Create `.vscode/mcp.json` in your workspace root:
215
+
216
+ ```json
217
+ {
218
+ "servers": {
219
+ "monnify": {
220
+ "type": "stdio",
221
+ "command": "npx",
222
+ "args": [
223
+ "-y",
224
+ "@monnify/mcp-server",
225
+ "--apiKey=YOUR_API_KEY",
226
+ "--secretKey=YOUR_SECRET_KEY",
227
+ "--contractCode=YOUR_CONTRACT_CODE",
228
+ "--env=sandbox"
229
+ ]
230
+ }
231
+ }
232
+ }
233
+ ```
234
+
235
+ Open the Copilot Chat panel, switch to **Agent mode**, and the Monnify tools will be available. Commit `.vscode/mcp.json` to share the setup with your team (credentials should come from environment variables — see [using environment variables](#using-environment-variables)).
236
+
237
+ ---
238
+
239
+ ### Windsurf
240
+
241
+ Add to `~/.codeium/windsurf/mcp_config.json`:
242
+
243
+ ```json
244
+ {
245
+ "mcpServers": {
246
+ "monnify": {
247
+ "command": "npx",
248
+ "args": [
249
+ "-y",
250
+ "@monnify/mcp-server",
251
+ "--apiKey=YOUR_API_KEY",
252
+ "--secretKey=YOUR_SECRET_KEY",
253
+ "--contractCode=YOUR_CONTRACT_CODE",
254
+ "--env=sandbox"
255
+ ]
256
+ }
257
+ }
258
+ }
259
+ ```
260
+
261
+ ---
262
+
263
+ ### Zed
264
+
265
+ Add to `~/.config/zed/settings.json` under `"context_servers"`:
266
+
267
+ ```json
268
+ {
269
+ "context_servers": {
270
+ "monnify": {
271
+ "command": {
272
+ "path": "npx",
273
+ "args": [
274
+ "-y",
275
+ "@monnify/mcp-server",
276
+ "--apiKey=YOUR_API_KEY",
277
+ "--secretKey=YOUR_SECRET_KEY",
278
+ "--contractCode=YOUR_CONTRACT_CODE",
279
+ "--env=sandbox"
280
+ ]
281
+ }
282
+ }
283
+ }
284
+ }
285
+ ```
286
+
287
+ ---
288
+
289
+ ### Continue.dev (VS Code / JetBrains)
290
+
291
+ Add to `~/.continue/config.json` under `"mcpServers"`:
292
+
293
+ ```json
294
+ {
295
+ "mcpServers": [
296
+ {
297
+ "name": "monnify",
298
+ "command": "npx",
299
+ "args": [
300
+ "-y",
301
+ "@monnify/mcp-server",
302
+ "--apiKey=YOUR_API_KEY",
303
+ "--secretKey=YOUR_SECRET_KEY",
304
+ "--contractCode=YOUR_CONTRACT_CODE",
305
+ "--env=sandbox"
306
+ ]
307
+ }
308
+ ]
309
+ }
310
+ ```
311
+
312
+ ---
313
+
314
+ ## Using environment variables
315
+
316
+ Avoid hardcoding credentials in config files by passing them via environment variables instead:
317
+
318
+ ```json
319
+ {
320
+ "mcpServers": {
321
+ "monnify": {
322
+ "command": "npx",
323
+ "args": ["-y", "@monnify/mcp-server"],
324
+ "env": {
325
+ "MONNIFY_API_KEY": "YOUR_API_KEY",
326
+ "MONNIFY_SECRET_KEY": "YOUR_SECRET_KEY",
327
+ "MONNIFY_CONTRACT_CODE": "YOUR_CONTRACT_CODE",
328
+ "MONNIFY_ENV": "sandbox"
329
+ }
330
+ }
331
+ }
332
+ }
333
+ ```
334
+
335
+ All CLI flags have an equivalent environment variable:
336
+
337
+ | CLI flag | Environment variable |
338
+ |-------------------|-----------------------------|
339
+ | `--apiKey` | `MONNIFY_API_KEY` |
340
+ | `--secretKey` | `MONNIFY_SECRET_KEY` |
341
+ | `--contractCode` | `MONNIFY_CONTRACT_CODE` |
342
+ | `--env` | `MONNIFY_ENV` |
343
+ | `--transport` | `MONNIFY_TRANSPORT` |
344
+ | `--port` | `MONNIFY_PORT` |
345
+ | `--tools` | `MONNIFY_TOOLS` |
346
+ | `--format` | `MONNIFY_RESPONSE_FORMAT` |
347
+
348
+ ---
349
+
350
+ ## Smart response formatting
351
+
352
+ The server automatically detects which client is connecting and adapts its responses:
353
+
354
+ | Client | Response format |
355
+ |--------|----------------|
356
+ | Claude Desktop, Claude Code CLI | Conversational Markdown with status icons, Naira formatting, and human-readable dates |
357
+ | Cursor, VS Code Copilot, Windsurf, Zed, Continue.dev | Clean JSON — machine-readable and easy to pipe into other tools |
358
+ | ChatGPT, Gemini | Conversational Markdown |
359
+
360
+ **Override the format** with the `--format` flag if the auto-detection doesn't match your workflow:
361
+
362
+ ```bash
363
+ # Force JSON for all clients (e.g. a custom integration)
364
+ npx -y @monnify/mcp-server --apiKey=... --format=json
365
+
366
+ # Force Markdown for all clients
367
+ npx -y @monnify/mcp-server --apiKey=... --format=markdown
368
+ ```
369
+
370
+ **What conversational responses look like:**
371
+
372
+ ```
373
+ ✅ Payment Initiated
374
+
375
+ Amount: ₦15,000.00
376
+ Reference: PAY-20240601-007
377
+ Customer: John Doe (john@example.com)
378
+ Checkout: https://checkout.monnify.com/pay/abc123
379
+ Expires: 1 Jul 2024, 11:59 PM WAT
380
+ ```
381
+
382
+ **What JSON responses look like (for engineering tools):**
383
+
384
+ ```json
385
+ {
386
+ "paymentReference": "PAY-20240601-007",
387
+ "totalPayable": 15000,
388
+ "checkoutUrl": "https://checkout.monnify.com/pay/abc123",
389
+ "paymentStatus": "PENDING"
390
+ }
391
+ ```
392
+
393
+ ---
394
+
395
+ ## All options
396
+
397
+ | Flag | Default | Description |
398
+ |------------------|-----------|-----------------------------------------------------|
399
+ | `--apiKey` | — | Your Monnify API key (required) |
400
+ | `--secretKey` | — | Your Monnify secret key (required) |
401
+ | `--contractCode` | — | Your Monnify contract code (required) |
402
+ | `--env` | `sandbox` | `sandbox` or `production` |
403
+ | `--transport` | `stdio` | `stdio` (local clients) or `http` (team deployments)|
404
+ | `--port` | `3000` | Port to listen on when using `--transport=http` |
405
+ | `--tools` | all | Comma-separated list of tool categories (see below) |
406
+ | `--format` | `auto` | `auto`, `markdown`, or `json` |
407
+ | `--httpToken` | — | Bearer token to authenticate HTTP `/mcp` requests |
408
+
409
+ ---
410
+
411
+ ## Available tools (25)
412
+
413
+ ### Collections (15)
414
+
415
+ | Tool | What it does |
416
+ |------|--------------|
417
+ | `monnify_initiate_payment` | Creates a payment and returns a checkout URL |
418
+ | `monnify_reserve_account` | Reserves a virtual bank account for a customer |
419
+ | `monnify_get_reserved_account` | Fetches details and status of a reserved account |
420
+ | `monnify_get_reserved_account_transactions` | Lists transactions received on a reserved account |
421
+ | `monnify_deallocate_reserved_account` | Permanently removes a reserved account |
422
+ | `monnify_get_transaction_status` | Checks the status of a transaction by reference |
423
+ | `monnify_get_transaction_details` | Fetches full details of a transaction |
424
+ | `monnify_get_all_transactions` | Lists transactions with filters and pagination |
425
+ | `monnify_create_invoice` | Creates a payment invoice with an expiry date |
426
+ | `monnify_process_refund` | Issues a full or partial refund |
427
+ | `monnify_pay_with_bank_transfer` | Starts a pay-by-bank-transfer flow |
428
+ | `monnify_charge_card` | Charges a card with PAN and CVV |
429
+ | `monnify_charge_card_token` | Charges a previously saved card token |
430
+ | `monnify_authorise_card_otp` | Submits OTP to complete a card charge |
431
+ | `monnify_authorise_card_3ds` | Completes 3DS verification for a card charge |
432
+
433
+ ### Direct Debit (5)
434
+
435
+ | Tool | What it does |
436
+ |------|--------------|
437
+ | `monnify_create_mandate` | Creates a direct debit mandate |
438
+ | `monnify_get_mandate_status` | Checks if a mandate is active and ready to debit |
439
+ | `monnify_debit_mandate` | Debits an active mandate |
440
+ | `monnify_get_mandate_debit_status` | Checks the status of a debit attempt |
441
+ | `monnify_cancel_mandate` | Cancels a mandate permanently |
442
+
443
+ ### Verification (4)
444
+
445
+ | Tool | What it does |
446
+ |------|--------------|
447
+ | `monnify_verify_bank_account` | Verifies an account number and returns the account name |
448
+ | `monnify_verify_bvn` | Matches a BVN against name, date of birth, and phone number |
449
+ | `monnify_verify_bvn_info` | Checks whether all submitted BVN details match holistically |
450
+ | `monnify_verify_nin` | Verifies a NIN and returns the associated record |
451
+
452
+ ### Utilities (1)
453
+
454
+ | Tool | What it does |
455
+ |------|--------------|
456
+ | `monnify_get_supported_banks` | Lists all supported banks and their codes |
457
+
458
+ ---
459
+
460
+ ## Limiting tool access
461
+
462
+ Scope the server to only the tools your use case needs. This reduces the surface area exposed to the AI client and keeps the tool list focused.
463
+
464
+ ```bash
465
+ # Verification and utilities only (e.g. a KYC onboarding agent)
466
+ npx -y @monnify/mcp-server --apiKey=... --secretKey=... --contractCode=... --tools=verification,utilities
467
+
468
+ # Collections only (e.g. a payment support agent)
469
+ npx -y @monnify/mcp-server --apiKey=... --secretKey=... --contractCode=... --tools=collections
470
+
471
+ # Collections + verification (e.g. a full checkout agent)
472
+ npx -y @monnify/mcp-server --apiKey=... --secretKey=... --contractCode=... --tools=collections,verification
473
+ ```
474
+
475
+ Available categories: `collections`, `directDebit`, `verification`, `utilities`
476
+
477
+ ---
478
+
479
+ ## Running as an HTTP server (team deployments)
480
+
481
+ Deploy a single shared instance and connect multiple clients to it — useful for team environments, CI pipelines, or production AI integrations.
482
+
483
+ **Step 1 — Generate a bearer token:**
484
+
485
+ ```bash
486
+ openssl rand -hex 32
487
+ # e.g. a3f8c2d1e4b5a6...
488
+ ```
489
+
490
+ **Step 2 — Start the server:**
491
+
492
+ ```bash
493
+ npx -y @monnify/mcp-server \
494
+ --apiKey=YOUR_API_KEY \
495
+ --secretKey=YOUR_SECRET_KEY \
496
+ --contractCode=YOUR_CONTRACT_CODE \
497
+ --env=production \
498
+ --transport=http \
499
+ --port=3000 \
500
+ --httpToken=YOUR_GENERATED_TOKEN
501
+ ```
502
+
503
+ The server will reject any `/mcp` request that does not carry `Authorization: Bearer YOUR_GENERATED_TOKEN`. If you start without `--httpToken`, it starts unauthenticated and logs a warning — acceptable for local development, not for any internet-facing deployment.
504
+
505
+ **Step 3 — Connect your AI client:**
506
+
507
+ ```bash
508
+ # Claude Code
509
+ claude mcp add monnify --transport http http://localhost:3000/mcp
510
+ ```
511
+
512
+ For clients that accept a custom header, set `Authorization: Bearer YOUR_GENERATED_TOKEN` alongside the endpoint URL.
513
+
514
+ **Step 4 — Put HTTPS in front of it.** Terminate TLS at a reverse proxy (nginx, Caddy, Cloudflare Tunnel) before exposing the server outside your local network. Never send credentials over plain HTTP.
515
+
516
+ Health check (no auth required): `GET /health`
517
+
518
+ ---
519
+
520
+ ## Testing locally without deploying
521
+
522
+ Run the server directly from source against the sandbox environment:
523
+
524
+ ```bash
525
+ git clone https://github.com/monnify/monnify-mcp-server
526
+ cd monnify-mcp-server
527
+ npm install
528
+ npm run build
529
+
530
+ node build/cli.js \
531
+ --apiKey=YOUR_API_KEY \
532
+ --secretKey=YOUR_SECRET_KEY \
533
+ --contractCode=YOUR_CONTRACT_CODE \
534
+ --env=sandbox
535
+ ```
536
+
537
+ Or use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to explore tools interactively:
538
+
539
+ ```bash
540
+ npx @modelcontextprotocol/inspector \
541
+ node $(pwd)/build/cli.js \
542
+ --apiKey=YOUR_API_KEY \
543
+ --secretKey=YOUR_SECRET_KEY \
544
+ --contractCode=YOUR_CONTRACT_CODE \
545
+ --env=sandbox
546
+ ```
547
+
548
+ Open `http://localhost:5173` in your browser to browse and invoke tools.
549
+
550
+ ---
551
+
552
+ ## Security
553
+
554
+ - Credentials are passed as CLI args or environment variables and never stored
555
+ - All API responses are filtered through a whitelist — internal Monnify fields are stripped before returning data to the AI client
556
+ - Destructive tools (deallocate, cancel mandate) are clearly labelled in their descriptions so the AI client warns before executing them
557
+ - Scope tool access with `--tools` to only expose what a given agent needs
558
+
559
+ ---
560
+
561
+ ## License
562
+
563
+ MIT — built by the [Monnify](https://monnify.com) team.
@@ -0,0 +1,11 @@
1
+ declare class TokenManager {
2
+ private cachedToken;
3
+ private expiresAt;
4
+ private inflightRequest;
5
+ getToken(): Promise<string>;
6
+ clearCache(): void;
7
+ private fetchNewToken;
8
+ }
9
+ export declare const tokenManager: TokenManager;
10
+ export {};
11
+ //# sourceMappingURL=tokenManager.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tokenManager.d.ts","sourceRoot":"","sources":["../../src/auth/tokenManager.ts"],"names":[],"mappings":"AASA,cAAM,YAAY;IAChB,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,SAAS,CAAa;IAC9B,OAAO,CAAC,eAAe,CAAgC;IAEjD,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IAajC,UAAU,IAAI,IAAI;YAKJ,aAAa;CAiD5B;AAED,eAAO,MAAM,YAAY,cAAqB,CAAC"}
@@ -0,0 +1,62 @@
1
+ import axios from "axios";
2
+ import { env } from "../config/env.js";
3
+ import { logger } from "../utils/logger.js";
4
+ import { MonnifyApiError } from "../utils/errors.js";
5
+ class TokenManager {
6
+ cachedToken = null;
7
+ expiresAt = 0;
8
+ inflightRequest = null;
9
+ async getToken() {
10
+ if (this.cachedToken && Date.now() < this.expiresAt) {
11
+ return this.cachedToken;
12
+ }
13
+ if (this.inflightRequest) {
14
+ return this.inflightRequest;
15
+ }
16
+ this.inflightRequest = this.fetchNewToken().finally(() => {
17
+ this.inflightRequest = null;
18
+ });
19
+ return this.inflightRequest;
20
+ }
21
+ clearCache() {
22
+ this.cachedToken = null;
23
+ this.expiresAt = 0;
24
+ }
25
+ async fetchNewToken() {
26
+ const { MONNIFY_API_KEY, MONNIFY_SECRET_KEY, MONNIFY_BASE_URL } = env();
27
+ const credentials = Buffer.from(`${MONNIFY_API_KEY}:${MONNIFY_SECRET_KEY}`).toString("base64");
28
+ logger.debug("Fetching new Monnify access token");
29
+ let response;
30
+ try {
31
+ response = await axios.post(`${MONNIFY_BASE_URL}/api/v1/auth/login`, {}, {
32
+ headers: {
33
+ Authorization: `Basic ${credentials}`,
34
+ "Content-Type": "application/json",
35
+ },
36
+ timeout: 30_000,
37
+ });
38
+ }
39
+ catch (error) {
40
+ if (axios.isAxiosError(error)) {
41
+ throw new MonnifyApiError(error.response?.data?.responseCode ?? "AUTH_FAILED", error.response?.data?.responseMessage ?? "Authentication failed", error.response?.status ?? 0);
42
+ }
43
+ throw error;
44
+ }
45
+ const body = response.data.responseBody;
46
+ const accessToken = body?.accessToken;
47
+ const expiresIn = body?.expiresIn;
48
+ if (!accessToken || !expiresIn) {
49
+ throw new MonnifyApiError("AUTH_FAILED", "Invalid auth response — missing token or expiry", 0);
50
+ }
51
+ this.cachedToken = accessToken;
52
+ // Subtract 60s buffer from expiry
53
+ this.expiresAt = Date.now() + (expiresIn - 60) * 1000;
54
+ logger.info("Monnify access token refreshed", {
55
+ expiresIn,
56
+ expiresAt: new Date(this.expiresAt).toISOString(),
57
+ });
58
+ return accessToken;
59
+ }
60
+ }
61
+ export const tokenManager = new TokenManager();
62
+ //# sourceMappingURL=tokenManager.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tokenManager.js","sourceRoot":"","sources":["../../src/auth/tokenManager.ts"],"names":[],"mappings":"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"}
package/build/cli.d.ts ADDED
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ export {};
3
+ //# sourceMappingURL=cli.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}