Skip to main content
Glama
SIBS Payment MCP

SIBS Payment MCP

SIBS Payment MCP

A Model Context Protocol (MCP) server that exposes the SIBS payment gateway as tools for AI agents — enabling LLMs to create checkouts, verify payments, issue refunds, and generate Multibanco references natively in any MCP-compatible environment.

MCP TypeScript SIBS License


What It Does

Bridges the SIBS payment gateway to the MCP ecosystem. Any AI agent or LLM-powered tool running in an MCP-compatible host (Claude Desktop, n8n, custom agents) can:

  • Check payment status in real time

  • Create checkout sessions with configurable payment methods

  • Capture, refund, or cancel authorised payments

  • Generate Multibanco references for ATM/homebanking payment

  • Initiate MB WAY push notifications to a customer's phone


Related MCP server: Magpie MCP Server

Architecture

flowchart LR
    A[AI Agent\nClaude / n8n] -->|MCP tool call| B[sibs-payment-mcp\nMCP Server]
    B -->|REST API| C[SIBS Gateway\nAPI]
    C -->|response| B
    B -->|structured result| A

    subgraph Tools
        T1[sibs_create_checkout]
        T2[sibs_payment_status]
        T3[sibs_capture_payment]
        T4[sibs_refund_payment]
        T5[sibs_cancel_payment]
        T6[sibs_generate_mb_reference]
        T7[sibs_mbway_payment]
        T8[sibs_test]
    end

Tools (8 total)

Tool

Description

sibs_create_checkout

Create a new checkout. Returns transactionID and hosted checkout URL

sibs_payment_status

Get payment state, amount, method, and timestamps by transaction ID

sibs_capture_payment

Capture an authorised payment — full or partial

sibs_refund_payment

Refund a captured payment — full or partial

sibs_cancel_payment

Cancel an authorised payment before capture

sibs_generate_mb_reference

Generate a Multibanco entity/reference for ATM payment

sibs_mbway_payment

Send MB WAY push to customer phone (351#912345678 format)

sibs_test

Validate credentials and connectivity


Stack

Component

Tool

Protocol

Model Context Protocol SDK

Language

TypeScript 5 + Node.js

Schema validation

Zod

Payment gateway

SIBS API (Portugal)

Build

tsc → dist/


Setup

Prerequisites

  • Node.js 18+

  • SIBS merchant account with API credentials

  • MCP-compatible host (Claude Desktop, n8n, custom agent)

1. Install

git clone https://github.com/RobsonAdvincula/sibs-payment-mcp.git
cd sibs-payment-mcp
npm install
npm run build

2. Configure environment

SIBS_BASE_URL=https://stargate.sibs.pt/m001/v1
SIBS_BEARER_TOKEN=your_bearer_token
SIBS_CLIENT_ID=your_client_id
SIBS_TERMINAL_ID=your_terminal_id

3. Add to MCP host

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "sibs-payment": {
      "command": "node",
      "args": ["/path/to/sibs-payment-mcp/dist/index.js"],
      "env": {
        "SIBS_BEARER_TOKEN": "...",
        "SIBS_CLIENT_ID": "...",
        "SIBS_TERMINAL_ID": "..."
      }
    }
  }
}

n8n MCP Client node: point to the compiled dist/index.js with the same env vars.


Example Interactions

Create a payment and send MB WAY:

Agent: "Create a €29.99 checkout for customer +351912345678"

→ sibs_create_checkout({ amount: 2999, currency: "EUR", paymentMethods: ["MBWAY"] })
→ sibs_mbway_payment({ transactionId: "txn_xxx", amount: 2999, customerPhone: "351#912345678" })

Result: "MB WAY notification sent. Customer has 4 minutes to confirm."

Verify and refund:

Agent: "Check transaction txn_abc and refund if paid"

→ sibs_payment_status({ transactionId: "txn_abc" })
  ← { status: "Success", amount: 4999 }
→ sibs_refund_payment({ transactionId: "txn_abc" })
  ← { refunded: true }

Payment Methods Supported

  • CARD — Visa / Mastercard

  • MBWAY — MB WAY mobile payment

  • REFERENCE — Multibanco ATM reference

  • COFIDIS — Instalments

  • PAYPAL — PayPal


License

MIT — free to use, adapt, and build on.


Built by Robson Advincula — AI & Automation Consultant

Available Tools

8 tools
sibs_cancel_paymentA

Cancel a SIBS payment authorization. Only works for payments not yet captured.

Inputs: transactionId (required).

sibs_capture_paymentA

Capture a previously authorized SIBS payment. Omit amount for full capture, or specify partial amount in minor units.

Inputs: transactionId (required), amount, currency.

sibs_create_checkoutB

Create a new SIBS checkout/payment. Amount in minor units (1000 = 10.00 EUR). Returns transactionID and checkout URL.

Inputs: amount (required), currency, customerEmail, customerPhone, +2 more.

sibs_generate_mb_referenceA

Generate a Multibanco (MB) payment reference. Returns entity, reference number, and amount for ATM/homebanking payment.

Inputs: amount (required), transactionId (required), currency, expiryDate.

sibs_mbway_paymentA

Initiate MB WAY payment. Sends notification to customer's MB WAY app. Phone format: '351#912345678'.

Inputs: amount (required), customerPhone (required), transactionId (required), currency.

sibs_payment_statusA

Get the status of a SIBS payment by transaction ID. Returns payment state, amount, method, and timestamps.

Inputs: transactionId (required).

sibs_refund_paymentA

Refund a SIBS payment. Omit amount for full refund, or specify partial amount in minor units.

Inputs: transactionId (required), amount, currency.

sibs_testA

Test SIBS API authentication. Verifies Bearer token and credentials are valid.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct operation: authentication testing, initiating MB WAY, creating a checkout, generating Multibanco references, querying status, and lifecycle actions (capture, refund, cancel). There is no meaningful overlap or ambiguity between tool purposes.

    Naming Consistency4/5

    Most tools follow the sibs_verb_noun pattern (create_checkout, capture_payment, refund_payment, cancel_payment, generate_mb_reference). Minor deviations exist: sibs_mbway_payment and sibs_payment_status omit an explicit verb, and sibs_test uses a bare verb, but the shared sibs_ prefix keeps the family recognizable.

    Tool Count5/5

    Eight tools is well-scoped for a payment MCP server covering authentication, multiple payment methods, status lookup, and payment lifecycle operations. Each tool serves a necessary and distinct role without unnecessary bloat or duplication.

    Completeness5/5

    The tool surface covers the core payment workflow end-to-end: create payments via MB WAY, checkout, and Multibanco reference, check status, capture, refund, and cancel. Authentication testing is also included, making the set self-sufficient for typical SIBS integration scenarios.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI agents to interact with multiple payment providers (Stripe, Paystack) through a unified API. Supports payment initialization, verification, refunds, customer management, and invoicing without requiring knowledge of specific provider implementations.
      2
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to access Magpie Payment Platform APIs for processing payments, creating checkout sessions, sending invoices, and managing payment links through natural conversation.
      68 npm
      2
      MIT