finstack-mcp-server

MCP server exposing CRS B2B (Finstack) customer data over the Model Context Protocol. Backed by the mware-portal chatbase API.

Tools

| Name | Purpose | |---|---| | finstack_search_customer | Fuzzy-match a customer by name and return candidate CIDs. Use when only a name is known. | | finstack_get_customer_summary | Non-PII summary for one customer: onboarding progress, products, API credentials, inspection status, recent billing. | | finstack_get_customer_revenue | Revenue for one customer over a date range, bucketed by day / week / month / quarter / year. | | finstack_get_customer_invoices | Paginated list of finalized invoices for one customer with full line-item breakdown. | | finstack_get_customer_pricing_config | Full configured pricing state for one customer: products, pricing addendums, and environment-user productPricing. Use to cross-check invoiced rates against contracted pricing. | | finstack_get_pricing_addendum_text | Extracted text from a pricing addendum PDF (with or without disclaimer). Server-side parses the PDF and returns plain text. | | finstack_get_vendors | Look up who to contact at an external vendor/partner (credit bureaus and data vendors like Equifax, TransUnion, Experian, CIC). OR-matches query across company, name, role, notes, location, and specialty tags; optional connection degree filter. |

Install

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

After install, the finstack-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 | |---|---|---|---| | FINSTACK_PROD_BASE_URL | yes | — | Base URL of the mware-portal API (production). | | FINSTACK_CHATBASE_SECRET | yes | — | Shared secret sent as X-Chatbase-Secret on every request. | | FINSTACK_DEV_BASE_URL | no | falls back to prod | Base URL for the dev environment. Used when a tool call passes environment: "dev". | | FINSTACK_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 and remote clients). | | MCP_PORT | no | 3002 | Port for the HTTP transport. Ignored when MCP_TRANSPORT=stdio. |

A starter file is included as .env.example.

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": {
    "finstack": {
      "command": "finstack-mcp-server",
      "env": {
        "MCP_TRANSPORT": "stdio",
        "FINSTACK_PROD_BASE_URL": "https://portal.example.com",
        "FINSTACK_CHATBASE_SECRET": "<your-secret>"
      }
    }
  }
}

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=3002 \
FINSTACK_PROD_BASE_URL=https://portal.example.com \
FINSTACK_CHATBASE_SECRET=<your-secret> \
finstack-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>:3002/mcp.

Docker

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

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

Tool call reference

finstack_search_customer

{ "q": "rentvine", "threshold": 0.8 }

q (required, min 2 chars) is matched case-insensitively. threshold (optional, 0.0–1.0, default 0.9) controls fuzziness — lower it if nothing comes back.

finstack_get_customer_summary

{ "customer_code": "CID18068" }

finstack_get_customer_revenue

{
  "customer_code": "CID18068",
  "type": "month",
  "start_date": "2025-05-08",
  "end_date": "2026-05-08"
}

Range caps depend on type: day ≤ 92 days, week ≤ 2 years, month/quarter ≤ 10 years, year ≤ 50 years.

finstack_get_customer_invoices

{ "customer_code": "CID18068", "page": 1, "per_page": 50 }

Identify the customer with either customer_code or user_id. page defaults to 1, per_page defaults to 50 and is silently capped at 100. Returns {customer_code, page, per_page, total_count, total_pages, invoices: [...]}, where each invoice carries its full items[] line-item breakdown.

finstack_get_customer_pricing_config

{ "customer_code": "CID18068" }

Returns {products, pricing_addendums, environment_users}. pricing_addendums[] entries carry id, name, status, quote_id, timestamps, has_pdf, has_pdf_without_disclaimer, and pdf_url / pdf_without_disclaimer_url. The PDF URLs require the chatbase secret to hit directly — use finstack_get_pricing_addendum_text to read the contents instead.

finstack_get_pricing_addendum_text

{ "id": 1234, "variant": "with_disclaimer" }

variant is optional and defaults to "with_disclaimer". Returns {addendum_id, variant, page_count, text}. The server fetches the PDF over the chatbase API and extracts text with pdf-parse; complex table layouts may run columns together but remain readable for LLM reasoning.

All tools accept an optional environment: "prod" | "dev" (default "prod").

Development

git clone https://github.com/StitchCredit/finstack-mcp-server.git
cd finstack-mcp-server
npm install
cp .env.example .env   # fill in FINSTACK_PROD_BASE_URL and FINSTACK_CHATBASE_SECRET
npm run build
npm start

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

License

Private — internal use within CRS Credit API.