Developer Tools
MCP Server
In a nutshell
Use Paystack's MCP Server to access Paystack APIs from AI assistants.
Warning
The MCP Server is currently in public preview. If you encounter any issues or have suggestions, you can create an issue or open a PR.
Copy linkIntroduction
The Model Context Protocol (MCP) is an open standard that allows AI assistants to connect to external tools and data sources.

The Paystack MCP Server uses this standard to expose the full Paystack API to AI agents through the Paystack OpenAPI spec. The server dynamically discovers documented endpoints and makes them available through MCP tools and resources, so you can interact with your Paystack integration using natural language.
Copy linkRequirements
Before setting up the MCP Server, ensure you have the following:
- Node.js v18 or later
- npm or yarn
- A Paystack test secret key
Copy linkGetting started
Install and run the server with npx:
npx @paystack/mcp-server --api-key sk_test_YOUR_KEY
| Option | CLI argument | Environment variable | Description |
|---|---|---|---|
| API key | --api-key sk_test_... | PAYSTACK_TEST_SECRET_KEY | The Paystack test secret key used to authenticate requests |
Security note
Only test keys (sk_test_*) are allowed. The server validates this at startup and rejects live keys to prevent unintended actions on your live integration.
Copy linkHow it works
The server exposes the Paystack API through tools and resources.
Copy linkTools
| Tool | Description |
|---|---|
get_paystack_operation | Fetch operation details such as method, path, and parameters by operation ID |
make_paystack_request | Execute a Paystack API request |
Copy linkResources
| Resource | URI | Description |
|---|---|---|
paystack_operation_list | paystack://operations/list | Lists all available Paystack operations and their details |
paystack_skill | paystack://skill | A knowledge resource with API documentation, code snippets, and best practices |
Copy linkExample
Here's what happens behind the scenes when you ask your assistant a question like "Get me the last 5 transactions on my Paystack business".
- The assistant browses the operations. It reads
paystack_operation_listto find the operation that matches your request.
{
"transaction_list": {
"name": "List Transactions",
"path": "/transaction",
"method": "get",
"queryParameter": [
{ "name": "perPage", "description": "Records per page" },
{ "name": "page", "description": "Page number" },
{ "name": "status", "description": "Filter by status" }
]
}
}
- The assistant fetches the full operation details. Once it picks
transaction_list, it callsget_paystack_operationto confirm the exact method, path, and parameters.
{
"operation_id": "transaction_list"
}
{
"name": "List Transactions",
"method": "get",
"path": "/transaction",
"queryParameter": [
{ "name": "perPage", "required": false },
{ "name": "page", "required": false },
{ "name": "status", "required": false }
]
}
- The assistant executes the request. It calls
make_paystack_requestwith the operation details and appendsperPage=5to the path.
{
"request": {
"method": "GET",
"path": "/transaction?perPage=5"
}
}
{
"status": true,
"message": "Transactions retrieved",
"data": [
{
"id": 4099260516,
"reference": "re4lyvq3s3",
"amount": 50000,
"currency": "NGN",
"status": "success"
},
{
"id": 4099260517,
"reference": "qa1b2c3d4e",
"amount": 120000,
"currency": "NGN",
"status": "success"
}
],
"meta": {
"total": 1284,
"perPage": 5,
"page": 1
}
}- The assistant replies. It uses the API response to generate a user-friendly summary.
Here are your last 5 transactions:
1. NGN 500.00, [email protected] (success)
2. NGN 1,200.00, [email protected] (success)
...Copy linkClient integration
The Paystack MCP Server works with any MCP-compatible client. Add the configuration below to your client's MCP config file. Use the Local build settings if you've cloned and built the server locally.
{
"mcpServers": {
"paystack": {
"command": "npx",
"args": ["@paystack/mcp-server", "--api-key", "sk_test_..."]
}
}
}
{
"mcpServers": {
"paystack": {
"command": "node",
"args": ["/path/to/paystack-mcp-server/build/index.js"],
"env": {
"PAYSTACK_TEST_SECRET_KEY": "sk_test_..."
}
}
}
}
Node.js path resolution
When using command: "node", ensure you're running Node v18 or later. If you use a version manager, you might need to provide the full path to your Node binary. Run which node on macOS/Linux or where node on Windows to get the path.
Copy linkPrompt recommendations
For the best results when using the MCP Server, be specific in your prompts and always include "Paystack" in your request.
| Good Prompt | Less effective prompt |
|---|---|
| "Initialize a Paystack transaction for 50000 NGN" | "Initialize a transaction" |
| "Create a customer with email [email protected] on my Paystack account" | "Create a customer" |
| "How can I send money with the Paystack API?" | "How can I send money?" |
| "Show me a cURL example for verifying a Paystack transaction" | "Show me a cURL example" |
A good prompt includes:
- What you want to do,
- Which Paystack feature or endpoint you need, and
- Specific parameters.
This helps the assistant select the correct operation from the Paystack API without guessing.
Copy linkTroubleshooting
| Problem | Solution |
|---|---|
| Server exits silently at startup | Check that PAYSTACK_TEST_SECRET_KEY is set or that you passed the --api-key flag |
| "Invalid key" error | The key must start with sk_test_; live keys are not allowed |
| Tools not appearing in client | Ensure the server is running and the client config path is correct |
| Request timeouts | Check network connectivity to api.paystack.co and ensure your firewall or proxy settings aren't blocking requests |
For more information, see the Paystack MCP Server repository on Github.