CheckSlip MCP

A deployable remote MCP server (Streamable HTTP) for verifying Thai bank transfer slips. It exposes MCP tools over HTTP so any MCP-compatible client can verify a slip's amount, receiver, transfer date, and detect duplicate usage.

This server runs on Replit and is built into the monorepo's Express service. The MCP endpoint is served at the root path (/mcp), protected by a full OAuth 2.1 flow so MCP clients (e.g. Claude's "Connect") can sign in. /health, /, and the OAuth discovery/authorization endpoints are public.

Endpoints

• POST /mcp — MCP Streamable HTTP (initialize + requests). Requires a valid OAuth access token (Authorization: Bearer <token>).
• GET /mcp — MCP server-to-client stream (requires an active session)
• DELETE /mcp — terminate an MCP session
• GET /health — { "ok": true, "name": "CheckSlip MCP", "version": "1.0.0" }
• GET / — basic server info
• GET /admin — password-gated merchant console (create/list/revoke/rotate keys)
• OAuth (public): GET /.well-known/oauth-protected-resource, GET /.well-known/oauth-authorization-server, POST /register (DCR), GET|POST /authorize, POST /token

Authentication (OAuth 2.1)

The /mcp endpoint is protected by an OAuth 2.1 Authorization Code flow with PKCE, designed for MCP clients like Claude's custom connector:

1. The client reads /.well-known/oauth-protected-resource (advertised via the WWW-Authenticate header on a 401) to discover the authorization server.
2. It registers dynamically via POST /register (DCR), then opens /authorize in a browser.
3. The user signs in with their Merchant Name and API Key (issued from the /admin console). On success an authorization code is redirected back.
4. The client exchanges the code at /token (verifying PKCE) for a short-lived JWT access token (signed with SESSION_SECRET, audience <base>/mcp) plus a rotating refresh token.

Merchants and their API keys are managed in the /admin console, gated by ADMIN_PASSWORD. A static MCP_AUTH_TOKEN is still accepted as a fallback for server-to-server callers when set, but is no longer required.

MCP tools

check_slip

Verifies a slip via a slip image, a QR payload, or a transaction reference.

Input:

{
  "slip_image_base64": "base64 PNG/JPEG (optional)",
  "qr_payload": "string (optional)",
  "transaction_ref": "string (optional)",
  "expected_amount": "number > 0 (optional)",
  "expected_receiver_name": "string (optional)",
  "expected_receiver_account_last4": "4 digits (optional)",
  "expected_transfer_date": "YYYY-MM-DD (optional)",
  "order_id": "string (optional)",
  "mark_as_used": "boolean (default false)"
}

At least one of slip_image_base64, qr_payload, or transaction_ref is required. When only slip_image_base64 is given (raw base64 or a data:image/...;base64, data URL), the server decodes the QR code from the image and uses it as the QR payload. The result is returned as JSON text content with status one of verified | failed | duplicate | provider_error | config_error.

Comparison rules:

• Amount: exact numeric match.
• Receiver name: case-insensitive, whitespace-trimmed.
• Receiver account last 4: digits only.
• Date: compares the YYYY-MM-DD part of the slip's transfer datetime.
• Fields you don't pass are omitted from checks (not reported as false).

When mark_as_used is true and all checks pass, the slip's transaction id is recorded so future checks of the same slip return status: "duplicate".

slip_checker_status

Returns configuration/health without exposing secrets (provider, whether an API URL/key is set, duplicate store path, auth config (OAuth enabled + whether the static token fallback is set), allowed-origins count).

Setup on Replit

1. The project already runs on Replit. Add these Secrets / env vars:

   Key	Required	Notes
   SESSION_SECRET	Yes	Signs OAuth access tokens and admin sessions. Server refuses to start without it.
   ADMIN_PASSWORD	Yes	Gates the /admin merchant console. Server refuses to start without it.
   MCP_AUTH_TOKEN	No	Optional static Bearer token fallback for server-to-server callers.
   SLIP_PROVIDER	No	mock (default), uex, or generic.
   ALLOWED_ORIGINS	No	Comma-separated allowlist. Empty allows requests with no Origin.
   UEX_ACCOUNT_NO	uex only	Secret. UEX bank account number (used in the request path).
   UEX_LICENSE_KEY	uex only	Secret. UEX x-license-key.
   UEX_ACCESS_KEY	uex only	Secret. UEX access-key.
   UEX_API_BASE_URL	No	UEX base URL (default https://api-fin.uexchange.io/v1/fin/bank).
   SLIP_API_URL	generic only	Custom provider verify endpoint.
   SLIP_API_KEY	generic only	Custom provider API key.
   SLIP_API_AUTH_HEADER	No	Header name for the key (default Authorization).
   SLIP_API_KEY_PREFIX	No	Prefix for the key value (default Bearer).
   SHOP_RECEIVER_NAME	No	Default receiver name for the mock provider.
   SHOP_RECEIVER_ACCOUNT_LAST4	No	Default receiver last 4 for the mock provider.

2. Run (development): the workflow runs the server automatically. To run the commands manually:

   pnpm --filter @workspace/api-server run dev
   

3. MCP endpoint (after publishing):

   https://<your-replit-url>/mcp
   

4. Authentication: point your MCP client at the /mcp URL and use its "Connect" flow. It will discover the OAuth endpoints, open the browser login, and ask for your Merchant Name and API Key (created in /admin). The client then attaches Authorization: Bearer <access_token> automatically.

   To create a merchant + API key, open https://<your-replit-url>/admin, sign in with ADMIN_PASSWORD, add a merchant, and copy the one-time API key.

Mock test

With SLIP_PROVIDER=mock, call check_slip with:

{
  "qr_payload": "MOCK_OK",
  "expected_amount": 1590,
  "expected_receiver_name": "ABC SHOP",
  "expected_receiver_account_last4": "1234",
  "order_id": "ORDER-TEST-001",
  "mark_as_used": true
}

Mock values:

• MOCK_OK → verified slip (amount 1590).
• MOCK_890 → verified slip (amount 890).
• MOCK_FAIL → provider reports not verified.

UEX provider (real Thai bank verification)

Verifies slips through the UEX (uexchange.io) Qr Scan API.

SLIP_PROVIDER=uex
UEX_ACCOUNT_NO=<your account number>   # secret
UEX_LICENSE_KEY=<your x-license-key>   # secret
UEX_ACCESS_KEY=<your access-key>       # secret
# UEX_API_BASE_URL defaults to https://api-fin.uexchange.io/v1/fin/bank

How it works:

• check_slip's qr_payload (or the QR decoded from slip_image_base64, or transaction_ref) is sent as the qrString to POST {UEX_API_BASE_URL}/{UEX_ACCOUNT_NO}/qrScan with the x-license-key and access-key headers.
• A response with inner statusCode: "0000" is a verified slip; its fields (transaction ref, amount, receiver name/account, transfer date, bank) are mapped into the internal slip shape.
• 8xx data errors such as 8404 ("Transaction Reference does not exist") are reported as failed (the slip is invalid/not found). System errors are reported as provider_error.

Switching to a custom provider

SLIP_PROVIDER=generic
SLIP_API_URL=https://your-slip-provider.example.com/verify
SLIP_API_KEY=your_api_key

The generic provider POSTs { qr_payload, transaction_ref } and normalizes common provider field names into the internal slip format.

Automated tests

Vitest + Supertest cover the OAuth 2.1 security boundary and the admin/merchant console. They run against the dev Postgres database (DATABASE_URL) and create their own uniquely-named merchants, cleaning up afterward.

pnpm --filter @workspace/api-server run test

Covered: DCR, authorize → token with PKCE (happy path + wrong verifier), single-use auth codes, refresh-token rotation invalidating the old token, exact aud/iss enforcement on /mcp, invalid/expired token rejection, merchant credential validation, and the admin password gate + create/revoke/rotate. The suite is registered as the test validation (CI) check.

Smoke test

Checks /health and prints example check_slip input (no MCP client needed):

pnpm --filter @workspace/scripts run smoke

Warning

This server verifies slips through a provider API, never from the picture alone. When you pass slip_image_base64, the server only reads the slip's QR code from the image and forwards that QR payload to the provider; the rest of the image is not trusted. Slips without a readable QR code must be supplied as a qr_payload or transaction_ref instead.