This repository is the integration surface for building AI-assisted products on ShaBaasPay: connect assistants and agents to PayTo (NPP) flows, agreement lifecycle, and payment initiation. It ships as:

• shabaaspay-mcp-server (npm) — stdio MCP for local tools and inspectors.
• Remote MCP (Streamable HTTP) — hosted endpoints for Cursor, VS Code, Antigravity, and other MCP clients that speak HTTP.

Model Context Protocol (MCP)

ShaBaasPay hosts remote MCP servers at:

| Environment | MCP URL | |-------------|---------| | Staging | https://mcp-staging.shabaas.com/mcp | | Production | https://mcp.shabaas.com/mcp |

OAuth: Clients that support MCP OAuth can use browser sign-in.

API key: You can instead send your ShaBaasPay API key in the Authorization header (plain value or Bearer <key>).

To run a local MCP server with npx (stdio), use your API key from the developers portal:

npx -y shabaaspay-mcp-server --api-key=YOUR_SHABAASPAY_API_KEY

Equivalent:

export SHABAAS_API_KEY=your-api-key
npx -y shabaaspay-mcp-server

Stdio auth: When using local stdio (npx or Docker), set SHABAAS_API_KEY in the client config or environment. Some clients also require "authorization" in tool arguments. Remote HTTP MCP uses the connection Authorization header or OAuth instead.

Tool permissions are enforced per client policy returned by the ShaBaasPay for your key (which tools are allowed). Treat API keys like production credentials and rotate them if needed.

See Model Context Protocol for the protocol overview.

Requirements

• Node.js 22+

Supported operations

A machine-readable catalog lives in docs/tool-catalog.json. Tool names include get_auth_token, create_payment_agreement, get_payment_agreement, initiate_payment, get_payment_initiation, initiate_direct_debit, update_bilateral_agreement, generate_invoice, list_active_payment_agreements, and get_todays_earnings.

GitHub MCP Registry

The manifest for registry listing is server.json (name: io.github.shabaaspay/shabaaspay-mcp-server).

Configuration

Environment variables

| Variable | Description | Required | Default | |----------|-------------|----------|---------| | SHABAAS_API_KEY | Your ShaBaas Pay API key | Yes (for stdio) | — | | HTTP_PORT | Port for HTTP server | No | 3001 |

Hosted MCP (HTTP)

Use the staging or production URL from Model Context Protocol (MCP) above. Prefer OAuth / Connect in the client UI when available so you do not embed long-lived keys in config.

Cursor — ~/.cursor/mcp.json:

{
  "mcpServers": {
    "shabaaspay": {
      "type": "http",
      "url": "https://mcp-staging.shabaas.com/mcp"
    }
  }
}

VS Code — MCP config (mcp.json):

{
  "servers": {
    "shabaaspay": {
      "type": "http",
      "url": "https://mcp-staging.shabaas.com/mcp"
    }
  }
}

Antigravity:

{
  "mcpServers": {
    "shabaaspay": {
      "type": "http",
      "serverUrl": "https://mcp-staging.shabaas.com/mcp"
    }
  }
}

For local stdio (npx or Docker), see Quick start (npm package).

Agent-first flow example

Typical lifecycle with minimal inputs:

1. create_payment_agreement with name, type, maximum_amount, frequency, number_of_transactions_permitted, and identifier (pay_id or bsb + account_number).
2. get_payment_agreement using returned payment_agreement_id to confirm status.
3. initiate_payment with payment_agreement_id and amount.
4. get_payment_initiation with returned payment_initiation_id to track settlement status.

Failure recovery example:

• If initiate_payment returns a business-rule style failure (for example inactive agreement), call get_payment_agreement with the same payment_agreement_id to inspect status and next actions before retrying.

Quick start (npm package)

Use Node.js 22+ (e.g. nvm use 22).

Run with npx

export SHABAAS_API_KEY=your-api-key
npx -y shabaaspay-mcp-server

The server starts on stdio and waits for an MCP client (Cursor, VS Code, Antigravity, MCP Inspector, etc.).

Test tools with MCP Inspector

export SHABAAS_API_KEY=your-api-key
npx -y @modelcontextprotocol/inspector npx -y shabaaspay-mcp-server

Open the URL printed in the terminal, go to Tools, pick a tool, and run it.

With Docker (after building the image below):

export SHABAAS_API_KEY=your-api-key
npx -y @modelcontextprotocol/inspector docker run -i --rm -e SHABAAS_API_KEY shabaaspay-mcp

MCP clients (local stdio via npx)

Local stdio uses

Cursor — ~/.cursor/mcp.json:

{
  "mcpServers": {
    "shabaaspay": {
      "command": "npx",
      "args": ["-y", "shabaaspay-mcp-server"],
      "env": {
        "SHABAAS_API_KEY": "YOUR_SHABAAS_API_KEY"
      }
    }
  }
}

VS Code — MCP config (mcp.json):

{
  "servers": {
    "shabaaspay": {
      "command": "npx",
      "args": ["-y", "shabaaspay-mcp-server"],
      "env": {
        "SHABAAS_API_KEY": "YOUR_SHABAAS_API_KEY"
      }
    }
  }
}

Antigravity:

{
  "mcpServers": {
    "shabaaspay": {
      "command": "npx",
      "args": ["-y", "shabaaspay-mcp-server"],
      "env": {
        "SHABAAS_API_KEY": "YOUR_SHABAAS_API_KEY"
      }
    }
  }
}

Restart your editor or agent client, then use natural language in chat (e.g. “list my active payment agreements”).

Docker (npm package)

Create a folder with a file named Dockerfile (do not paste these lines into the terminal):

FROM node:22-alpine

WORKDIR /app

RUN npm install -g shabaaspay-mcp-server

USER node

CMD ["shabaaspay-mcp-server"]

Build and run:

docker build -t shabaaspay-mcp .
docker run -i --rm -e SHABAAS_API_KEY=your-api-key shabaaspay-mcp

The -i flag keeps stdin open for MCP stdio.

MCP clients (local stdio via Docker)

After docker build -t shabaaspay-mcp ., use the same command / args / env pattern. The image name (shabaaspay-mcp) must be the last argument in args.

Cursor — ~/.cursor/mcp.json ("command": "docker"):

{
  "mcpServers": {
    "shabaaspay-docker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SHABAAS_API_KEY",
        "shabaaspay-mcp"
      ],
      "env": {
        "SHABAAS_API_KEY": "YOUR_SHABAAS_API_KEY"
      }
    }
  }
}

VS Code — MCP config (mcp.json):

{
  "servers": {
    "shabaaspay-docker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SHABAAS_API_KEY",
        "shabaaspay-mcp"
      ],
      "env": {
        "SHABAAS_API_KEY": "YOUR_SHABAAS_API_KEY"
      }
    }
  }
}

If VS Code reports executable file not found, set "command" to the output of which docker.

Antigravity (use full path to docker):

{
  "mcpServers": {
    "shabaaspay-docker": {
      "command": "/usr/local/bin/docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SHABAAS_API_KEY",
        "shabaaspay-mcp"
      ],
      "env": {
        "SHABAAS_API_KEY": "YOUR_SHABAAS_API_KEY"
      }
    }
  }
}

Replace /usr/local/bin/docker with your path from which docker if it differs.

Restart your editor or agent client after saving the config.

License

MIT — see LICENSE.