mware-mcp-server

MCP server exposing CRS mware (B2B middleware) over the Model Context Protocol. Logs in with admin credentials, caches the JWT, and proxies read-only calls to the mware Spring API.

Tools

| Name | Purpose | |---|---| | mware_find_customer | Case-insensitive name substring → matching customers (UUID id, externalId/CID, name). | | mware_get_user_config | All config entries for one user (rate limits, products, billing codes, pricing). | | mware_request_logs | Most recent 40 request logs (sorted by createdAt DESC). Optional filters: request_id, applicant, customer_code, customer_name. | | mware_get_retention | Raw request/response payloads for one request log id (upstream + client request/response + headers). | | mware_get_billing | Aggregated billing for a date range: grand totals, per-customer rollups (sorted by net amount), per-product rollups. |

All tools require ROLE_ADMIN on the upstream mware API. All accept an optional environment: "prod" \| "dev" (default "prod").

Install

npm install -g @crscreditapi/mware-mcp-server

After install, the mware-mcp-server binary is on your PATH.

Configuration

The server reads configuration from environment variables (also loaded from a local .env file via dotenv).

| Variable | Required | Default | Description | |---|---|---|---| | MWARE_PROD_BASE_URL | yes | — | Base URL of the mware API (production). Must include the /api context path. | | MWARE_PROD_USERNAME | yes | — | Admin username for POST /users/login. | | MWARE_PROD_PASSWORD | yes | — | Admin password for POST /users/login. | | MWARE_DEV_BASE_URL | no | falls back to prod | Dev base URL. Used when a tool call passes environment: "dev". | | MWARE_DEV_USERNAME | no | falls back to prod | Dev admin username. | | MWARE_DEV_PASSWORD | no | falls back to prod | Dev admin password. | | MWARE_TIMEOUT_MS | no | 30000 | Per-request timeout in milliseconds. | | MCP_TRANSPORT | no | stdio | Transport mode: stdio (for Claude Code and other CLI clients) or http (for n8n / remote clients). | | MCP_PORT | no | 3003 | Port for the HTTP transport. Ignored when MCP_TRANSPORT=stdio. |

A starter file is included as .env.example.

Auth

On startup the client lazily POSTs to /users/login with the configured username/password, caches the returned JWT (using the upstream expires value, or a 55-minute TTL if absent), and sends Authorization: Bearer <token> on every request. On a 401 the cached token is cleared and one retry is attempted.

Usage

Stdio (Claude Code, Claude Desktop, other CLI clients)

Add an entry to your MCP config (.mcp.json for Claude Code, claude_desktop_config.json for Claude Desktop):

{
  "mcpServers": {
    "mware": {
      "command": "mware-mcp-server",
      "env": {
        "MCP_TRANSPORT": "stdio",
        "MWARE_PROD_BASE_URL": "https://mware.example.com/api",
        "MWARE_PROD_USERNAME": "<admin-email>",
        "MWARE_PROD_PASSWORD": "<admin-password>"
      }
    }
  }
}

The client launches the process; tool calls travel over stdio. No port to open.

HTTP (n8n, remote MCP clients)

Run it as a long-lived service:

MCP_TRANSPORT=http \
MCP_PORT=3003 \
MWARE_PROD_BASE_URL=https://mware.example.com/api \
MWARE_PROD_USERNAME=<admin-email> \
MWARE_PROD_PASSWORD=<admin-password> \
mware-mcp-server

Endpoints:

• POST / and POST /mcp — MCP requests (streamable HTTP transport)
• GET /health — health check, returns {"status":"ok","uptime":<seconds>}

Point your client at http://<host>:3003/mcp.

Docker

FROM node:20-alpine
RUN npm install -g @crscreditapi/mware-mcp-server
ENV MCP_TRANSPORT=http MCP_PORT=3003
EXPOSE 3003
CMD ["mware-mcp-server"]

Pass the MWARE_* variables at runtime (e.g. via --env-file or an orchestrator's secret store).

Tool call reference

mware_find_customer

{ "query": "unlock", "limit": 20 }

query is matched case-insensitively as a substring of name. limit (optional, 1–100, default 20) caps the result count. Returns { query, count, matches: [{ id, externalId, name }] }.

The upstream /customers endpoint has no name search, so this tool fetches a customer page (size 500) and filters client-side.

mware_get_user_config

{ "user_id": "e98794ff-d151-4205-bdbe-b654c558474d" }

Returns { user_id, count, configs: [...] } where each config has configName, queryString, dailyMaxRequests, monthlyMaxRequests, billingCode, product, isEnabled, isDefault, productPricing, and friends.

mware_request_logs

{ "customer_code": "CID11117" }

All filters are optional; combine them to narrow down. The upstream endpoint sorts by createdAt DESC, so you always get the most recent page (size 40):

• request_id — exact UUID match
• applicant — substring on the applicant name
• customer_code — CID, routed through the upstream composite substring search
• customer_name — customer name, also routed through composite (ignored if customer_code is set)

mware_get_retention

{ "request_log_id": "fa2eb0b3-cc3a-4ecf-a336-ccf7bfff3bc8" }

Returns the stored payloads for that request: rawRequest, rawResponse, rawClientRequest, rawClientResponse, rawRequestHeaders, rawResponseHeaders, plus userId and type. Responses can be large (100 KB+ for credit reports).

mware_get_billing

{
  "start_day": "2026-05-01T00:00:00Z",
  "end_day":   "2026-05-08T23:59:59Z"
}

Both dates are ISO-8601 instants. Returns:

{
  "window":  { "start": "...", "end": "..." },
  "totals":  { "rows", "customers", "requests", "total_amount", "refund_amount", "net_amount" },
  "by_customer": [{ "client_name", "client_num", "requests", "total_amount", "refund_amount", "net_amount" }, "..."],
  "by_product":  [{ "product",     "requests", "total_amount", "refund_amount", "net_amount" }, "..."]
}

by_customer and by_product are sorted descending by net_amount. Backed by GET /api/billing/total (the newer pricing engine — computes amounts from per-config pricing/tiers).

Development

git clone https://github.com/StitchCredit/mware-mcp-server.git
cd mware-mcp-server
npm install
cp .env.example .env   # fill in MWARE_PROD_BASE_URL, MWARE_PROD_USERNAME, MWARE_PROD_PASSWORD
npm run build
npm start

For stdio mode while iterating, set MCP_TRANSPORT=stdio in .env and point your MCP client's config at the local dist/index.js:

{
  "mcpServers": {
    "mware": {
      "command": "node",
      "args": ["/absolute/path/to/mware-mcp-server/dist/index.js"]
    }
  }
}

License

Private — internal use within CRS Credit API.