Sign in

Developer Tools

MCP Server

View as Markdown

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.

Image showing how the Paystack MCP Server works

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
OptionCLI argumentEnvironment variableDescription
API key--api-key sk_test_...PAYSTACK_TEST_SECRET_KEYThe 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

ToolDescription
get_paystack_operationFetch operation details such as method, path, and parameters by operation ID
make_paystack_requestExecute a Paystack API request

Copy linkResources

ResourceURIDescription
paystack_operation_listpaystack://operations/listLists all available Paystack operations and their details
paystack_skillpaystack://skillA 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".

  1. The assistant browses the operations. It reads paystack_operation_list to 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" }
    ]
  }
}
  1. The assistant fetches the full operation details. Once it picks transaction_list, it calls get_paystack_operation to 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 }
  ]
}
  1. The assistant executes the request. It calls make_paystack_request with the operation details and appends perPage=5 to the path.
{
  "request": {
    "method": "GET",
    "path": "/transaction?perPage=5"
  }
}
{
  "status": true,
  "message": "Transactions retrieved",
  "data": [
    {
      "id": 4099260516,
      "reference": "re4lyvq3s3",
      "amount": 50000,
      "currency": "KES",
      "status": "success"
    },
    {
      "id": 4099260517,
      "reference": "qa1b2c3d4e",
      "amount": 120000,
      "currency": "KES",
      "status": "success"
    }
  ],
  "meta": {
    "total": 1284,
    "perPage": 5,
    "page": 1
  }
}
  1. The assistant replies. It uses the API response to generate a user-friendly summary.
Here are your last 5 transactions:
1. KES 500.00, [email protected] (success)
2. KES 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 PromptLess effective prompt
"Initialize a Paystack transaction for 50000 KES""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:

  1. What you want to do,
  2. Which Paystack feature or endpoint you need, and
  3. Specific parameters.

This helps the assistant select the correct operation from the Paystack API without guessing.

Copy linkTroubleshooting

ProblemSolution
Server exits silently at startupCheck that PAYSTACK_TEST_SECRET_KEY is set or that you passed the --api-key flag
"Invalid key" errorThe key must start with sk_test_; live keys are not allowed
Tools not appearing in clientEnsure the server is running and the client config path is correct
Request timeoutsCheck 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.

Was this page helpful?