# MCP Server

> Use Paystack's MCP Server to access Paystack APIs from AI assistants.

<callout type="warning">

The MCP Server is currently in public preview. If you encounter any issues or have suggestions, you can [create an issue](https://github.com/PaystackOSS/paystack-mcp-server/issues) or [open a PR](https://github.com/PaystackOSS/paystack-mcp-server/pulls).

</callout>

## Introduction

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard that allows AI assistants to connect to external tools and data sources.

![Image showing how the Paystack MCP Server works](./images/paystack_mcp_architecture.png)

The Paystack MCP Server uses this standard to expose the full Paystack API to AI agents through the [Paystack OpenAPI spec](https://github.com/PaystackOSS/openapi). 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.

## Requirements

Before setting up the MCP Server, ensure you have the following:

- Node.js v18 or later
- npm or yarn
- A Paystack test secret key

## Getting started

Install and run the server with `npx`:

```shell
npx @paystack/mcp-server --api-key sk_test_YOUR_KEY
```

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      CLI argument
    </th>
    
    <th>
      Environment variable
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      API key
    </td>
    
    <td>
      <code>
        --api-key sk_test_...
      </code>
    </td>
    
    <td>
      <code>
        PAYSTACK_TEST_SECRET_KEY
      </code>
    </td>
    
    <td>
      The Paystack test secret key used to authenticate requests
    </td>
  </tr>
</tbody>
</table>

<callout type="danger" title="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.

</callout>

## How it works

The server exposes the Paystack API through tools and resources.

### Tools

<table>
<thead>
  <tr>
    <th>
      Tool
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        get_paystack_operation
      </code>
    </td>
    
    <td>
      Fetch operation details such as method, path, and parameters by operation ID
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        make_paystack_request
      </code>
    </td>
    
    <td>
      Execute a Paystack API request
    </td>
  </tr>
</tbody>
</table>

### Resources

<table>
<thead>
  <tr>
    <th>
      Resource
    </th>
    
    <th>
      URI
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        paystack_operation_list
      </code>
    </td>
    
    <td>
      <code>
        paystack://operations/list
      </code>
    </td>
    
    <td>
      Lists all available Paystack operations and their details
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        paystack_skill
      </code>
    </td>
    
    <td>
      <code>
        paystack://skill
      </code>
    </td>
    
    <td>
      A knowledge resource with API documentation, code snippets, and best practices
    </td>
  </tr>
</tbody>
</table>

### Example

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.

```json
{
  "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.

```json
{
  "operation_id": "transaction_list"
}
```

```json
{
  "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.

```json
{
  "request": {
    "method": "GET",
    "path": "/transaction?perPage=5"
  }
}
```

<localized-snippet src="developer-tools/mcp-server/list-transactions-response">



</localized-snippet>

1. **The assistant replies.** It uses the API response to generate a user-friendly summary.

<localized-snippet src="developer-tools/mcp-server/assistant-reply">



</localized-snippet>

## Client 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.

<code-tabs :labels="{"hosted":"Hosted (npx)","local":"Local build"}">
<template v-slot:hosted="">

```json
{
  "mcpServers": {
    "paystack": {
      "command": "npx",
      "args": ["@paystack/mcp-server", "--api-key", "sk_test_..."]
    }
  }
}
```

</template>

<template v-slot:local="">

```json
{
  "mcpServers": {
    "paystack": {
      "command": "node",
      "args": ["/path/to/paystack-mcp-server/build/index.js"],
      "env": {
        "PAYSTACK_TEST_SECRET_KEY": "sk_test_..."
      }
    }
  }
}
```

</template>
</code-tabs>

<callout type="warning" title="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.

</callout>

## Prompt recommendations

For the best results when using the MCP Server, be specific in your prompts and always include "Paystack" in your request.

<table-width :even="true">
<table>
<thead>
  <tr>
    <th>
      Good Prompt
    </th>
    
    <th>
      Less effective prompt
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      "Initialize a Paystack transaction for 50000 <localized-value page-key="markets" path="currency_code">
        
      </localized-value>
      
      "
    </td>
    
    <td>
      "Initialize a transaction"
    </td>
  </tr>
  
  <tr>
    <td>
      "Create a customer with email <a href="mailto:user@example.com">
        user@example.com
      </a>
      
       on my Paystack account"
    </td>
    
    <td>
      "Create a customer"
    </td>
  </tr>
  
  <tr>
    <td>
      "How can I send money with the Paystack API?"
    </td>
    
    <td>
      "How can I send money?"
    </td>
  </tr>
  
  <tr>
    <td>
      "Show me a cURL example for verifying a Paystack transaction"
    </td>
    
    <td>
      "Show me a cURL example"
    </td>
  </tr>
</tbody>
</table>
</table-width>

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.

## Troubleshooting

<table-width wider="1" wider-width="30%">
<table>
<thead>
  <tr>
    <th>
      Problem
    </th>
    
    <th>
      Solution
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Server exits silently at startup
    </td>
    
    <td>
      Check that <code>
        PAYSTACK_TEST_SECRET_KEY
      </code>
      
       is set or that you passed the <code>
        --api-key
      </code>
      
       flag
    </td>
  </tr>
  
  <tr>
    <td>
      "Invalid key" error
    </td>
    
    <td>
      The key must start with <code>
        sk_test_
      </code>
      
      ; live keys are not allowed
    </td>
  </tr>
  
  <tr>
    <td>
      Tools not appearing in client
    </td>
    
    <td>
      Ensure the server is running and the client config path is correct
    </td>
  </tr>
  
  <tr>
    <td>
      Request timeouts
    </td>
    
    <td>
      Check network connectivity to <code>
        api.paystack.co
      </code>
      
       and ensure your firewall or proxy settings aren't blocking requests
    </td>
  </tr>
</tbody>
</table>
</table-width>

For more information, see the [Paystack MCP Server repository](https://github.com/PaystackOSS/paystack-mcp-server) on Github.
