Overview

The Pagos MCP Server implements a lightweight Model Context Protocol (MCP) service for fast credit card BIN/IIN lookup. It exposes a simple HTTP API that returns card metadata (brand, scheme, card type, issuing bank, country, etc.) for a given BIN/IIN. This makes it easy to enrich card numbers in payment flows, risk scoring, routing, or analytics without embedding large datasets in each application.

The server is designed for developer usage: it can be deployed locally for development, in containers for production, or integrated into serverless stacks. It focuses on low-latency lookups, secure access (API key + TLS), and an extensible API that will receive additional endpoints and features in future releases.

Features

Fast BIN/IIN lookups via a small, RESTful HTTP API
Lightweight deployment: run from source or container
Configurable API key authentication and TLS support
JSON responses with standard BIN metadata fields (scheme, brand, type, country, issuer)
Simple rate limiting and logging hooks for integration into payment flows
Extensible: planned expansions for bulk queries, batch uploads, and richer metadata

Installation / Configuration

Clone the repository and run from source or build a container image. The examples below show typical commands; adjust to your environment.

Clone repository:

git clone https://github.com/pagos-ai/pagos-mcp.git
cd pagos-mcp

Build and run with Docker:

# Build image
docker build -t pagos-mcp .

# Run container (example)
docker run -p 8080:8080 \
  -e API_KEY="your_api_key_here" \
  -e PORT=8080 \
  -e LOG_LEVEL=info \
  pagos-mcp

Run locally (if a binary or script is provided):

# Example environment variables
export API_KEY="your_api_key_here"
export PORT=8080

# Start the server (example command)
./pagos-mcp --port $PORT

Common environment variables / configuration options:

PORT: HTTP port to listen on (default: 8080)
API_KEY: required API key for requests
DATA_FILE_PATH: path to BIN dataset file (CSV/JSON) used at startup
LOG_LEVEL: debug|info|warn|error
TLS_CERT / TLS_KEY: file paths to enable HTTPS

Security recommendations:

Always run behind TLS in production and keep the API key secret.
Front your service with an API gateway or proxy for additional rate limiting / auth.
Rotate API keys periodically.

API (Examples)

Basic lookup endpoints (examples — exact paths may vary by release):

GET single BIN:

curl -H "X-API-Key: your_api_key_here" \
  "https://mcp.example.com/v1/bin/45717360"

POST bulk lookup:

curl -X POST -H "Content-Type: application/json" -H "X-API-Key: your_api_key_here" \
  -d '{"bins":["45717360","510510"]}' \
  "https://mcp.example.com/v1/bins/lookup"

Example single response (JSON):

{
  "bin": "457173",
  "length": 6,
  "scheme": "visa",
  "brand": "Visa",
  "card_type": "debit",
  "category": "consumer",
  "issuing_bank": {
    "name": "Example Bank",
    "country": {
      "name": "United States",
      "alpha2": "US"
    },
    "url": "https://examplebank.com",
    "phone": "+1-800-555-0100"
  }
}

Common response fields:

Field	Description
bin	First 6 (or configured length) digits used as the key
length	Number of digits in the BIN key
scheme	Card network (visa, mastercard, amex, etc.)
brand	Brand or marketing name
card_type	debit, credit, prepaid
category	consumer, corporate, etc.
issuing_bank	Object with issuer name, country, URL, phone
country	Object with name and ISO2 code

Available Resources

GitHub repository: https://github.com/pagos-ai/pagos-mcp — source code, issues, and contribution notes
API docs / OpenAPI: Check the repo for a bundled OpenAPI/Swagger spec (often provided in /docs or /openapi.yaml)
Dockerfile: Build from source and run in containers
Example dataset: repository may include a sample BIN dataset for local testing
Postman collection: look for a /postman or /collections directory if present

If you need to extend the server, the repository is usually structured so you can replace the dataset loader, add middleware for auth, or extend endpoints for bulk operations.

Use Cases

E-commerce validation: Quickly determine card network and type to steer UI messaging (show card logo, detect prepaid/debit). Example: on card entry, extract the first 6 digits, query the MCP server, and display the detected brand.
Fraud scoring and risk decisions: Enrich transaction events with issuing country and bank to augment fraud models. Example: if a BIN maps to an issuer in a high-risk jurisdiction, raise the scoring weight.
Payment routing: Route transactions to different processors based on BIN metadata (e.g., card scheme or issuer). Example: route Maestro/Local-network BINs to a local acquirer to reduce fees.
Analytics and reporting: Aggregate BIN-level metrics (counts by scheme, issuer, country) without shipping full card numbers. Example: record BIN metadata alongside transaction logs for cohort analysis.
Compliance and filtering: Flag BINs tied to sanctioned countries or blocked issuers before authorizing transactions.

Notes & Roadmap

This MCP server currently focuses on core BIN lookup capabilities and secure, low-latency access. Future enhancements planned include expanded API endpoints (bulk/batch upload and results), richer metadata fields, better dataset management, and tighter integration examples (SDKs/clients). Check the GitHub repository for milestone and roadmap details.

Pagos MCP Server for Credit Card BIN Lookup