smart-npv-mcp

An MCP server that turns the Smart NPV mortgage-advisor CRM into tools your AI agent can call.

שרת MCP שמחבר סוכני AI (Claude, Cursor, Hermes ועוד) ישירות למערכת Smart NPV, כדי לקרוא ולעדכן תיקי לקוחות, סטטוסים, מסמכים וסימולציות בשפה טבעית.

Built at BeAi. Works with any Smart NPV account.

⚠️ Community project. Not affiliated with or endorsed by Smart NPV. Built against their public API documentation.

Table of contents

• What is this?

• Why would I want it?

• How it works

• Requirements

• Installation

• Configuration

• Connecting to an MCP client

• The authentication model

• Tool reference (32 tools)

• Worked example: a pipeline guardian

• Example calls and responses

• Error handling

• Troubleshooting

• Development

• Project status and roadmap

• Contributing

• License

Related MCP server: AI-Assisted CRM MCP Server

What is this?

Three pieces come together here:

• Smart NPV is a CRM built for Israeli mortgage advisors: it manages client files, mortgage calculations, document checklists, and workflow stages. It exposes a REST API (behind a paid tier).

• MCP (Model Context Protocol) is an open standard that lets AI agents call external tools through a uniform interface. Instead of hand-writing HTTP requests, an agent gets a clean, typed set of tools it can reason about and call.

• This server is the bridge. It wraps every documented Smart NPV endpoint as an MCP tool, so any MCP-capable agent can operate the CRM: list clients, read a client's status and documents, add a status, upload a file, record a payment, run simulations, and more.

In one sentence: it lets an AI agent operate Smart NPV for you, safely and deterministically, instead of clicking through the UI.

Why would I want it?

A mortgage advisor working solo juggles dozens of active files, each moving through an 8-stage workflow that can take months. Files fall through the cracks. An AI agent connected through this server can, for example:

• Watch the pipeline. Every morning, list all active clients, read each one's status and predicted stage date, and flag the ones that have stalled: "3 files are past their stage deadline. Client X has had no movement for 12 days."

• Chase missing documents. Read a client's document list, compare against the required checklist, and draft a reminder for exactly what is missing.

• Keep the CRM tidy. Record a status change or file an uploaded document back into the right client, automatically.

• Answer questions. "How many leads came in this month?" "What is the status of the Cohen file?"

The agent decides what to do; this server gives it the hands to do it in Smart NPV.

How it works

flowchart LR
    A["AI agent<br/>(Claude / Cursor / Hermes)"] -- "MCP (stdio)" --> B["smart-npv-mcp<br/>server"]
    B -- "HTTPS + api_key" --> C["Smart NPV API<br/>www.snpv.co.il"]
    C -- "JSON" --> B
    B -- "tool result" --> A

The agent speaks MCP over stdio. This server translates each tool call into the correct Smart NPV HTTP request (injecting your api_key), and returns the JSON response back to the agent.

Requirements

• Node.js 18+ (uses the built-in fetch, FormData, and Blob).

• A Smart NPV account with API access. The API sits behind Smart NPV's extended (paid) subscription. You will need an API key from them. Some tools also require the Premium tier (marked below).

Installation

Option A: via npx (recommended, once published to npm)

No install needed; your MCP client runs it on demand:

npx -y smart-npv-mcp

Option B: from source

git clone https://github.com/binyaminboukaya/smart-npv-mcp.git
cd smart-npv-mcp
npm install
npm run build

Configuration

The server reads four environment variables:

For local development, copy the template:

cp .env.example .env
# then edit .env and paste your key

How to get a key: contact Smart NPV support / your account manager and ask to enable API access on the extended subscription. They issue the api_key.

Connecting to an MCP client

Add an entry to your client's MCP config. The examples below assume the key is in SMARTNPV_API_KEY.

{
  "mcpServers": {
    "smart-npv": {
      "command": "npx",
      "args": ["-y", "smart-npv-mcp"],
      "env": { "SMARTNPV_API_KEY": "your-key-here" }
    }
  }
}

{
  "mcpServers": {
    "smart-npv": {
      "command": "npx",
      "args": ["-y", "smart-npv-mcp"],
      "env": { "SMARTNPV_API_KEY": "your-key-here" }
    }
  }
}

{
  "mcpServers": {
    "smart-npv": {
      "command": "node",
      "args": ["/absolute/path/to/smart-npv-mcp/dist/index.js"],
      "env": {
        "SMARTNPV_BASE_URL": "https://www.snpv.co.il",
        "SMARTNPV_API_KEY": "your-key-here"
      }
    }
  }
}

After adding the config, restart the client. You should see the smart-npv tools appear.

The authentication model

Smart NPV passes the api_key differently depending on the request type. This server handles it for you automatically; you never pass api_key as a tool argument.

Tool reference (32 tools)

Legend: Premium = requires the Premium tier of the subscription. Required arguments are in bold.

Working with client data? See docs/client-fields.md for the full client field schema — including the _1 / _2 two-borrower model that every personal field uses.

Worked example: a pipeline guardian

The most valuable pattern. Goal: every morning, surface files that have stalled.

What you say to the agent:

"Go over all my active clients and tell me which ones have not moved recently or are past their stage deadline."

What the agent does with these tools:

1. list_clients with lead: false to get active files.

2. For each client, get_client_status to read the current stage and its predicted date.

3. Compares dates, and reports the stalled ones back to you in plain language.

What you get back:

"3 files need attention: Levi (stage 2, 11 days no movement), Cohen (past the appraisal deadline by 4 days), Mizrahi (documents requested 8 days ago, none received)."

Then, still in the same conversation:

"Draft a WhatsApp reminder to Mizrahi for the missing documents."

The agent uses get_client_documentations to see what is missing and drafts the message. You approve and send. No file falls through the cracks.

Example calls and responses

Tool arguments are plain JSON. A few illustrative calls (exact response shape depends on your Smart NPV account, since this is built against the documented API):

List the 25 most recent active clients

// tool: list_clients
{ "limit": 25, "offset": 0, "lead": false }

Read one client's status

// tool: get_client_status
{ "uuid": "12345678-1234-1234-1234-123456789109" }

Add a status to a client

// tool: add_status
{ "params": { "uuid": "12345678-...", "status_id": 4, "note": "Documents received" } }

Upload a document

// tool: upload_document
{
  "uuid": "12345678-...",
  "file_name": "tabu_nispach.pdf",
  "file_path": "/Users/me/Downloads/tabu_nispach.pdf"
}

Record a retainer payment

// tool: add_payment
{ "uuid": "12345678-...", "params": { "amount": 2000, "type": "retainer" } }

A successful call returns the API's JSON as text. On failure the result is marked as an error (see below).

Note on params: several write endpoints accept a free-form params object whose exact inner fields are defined by Smart NPV and are not fully published. Pass the fields the CRM expects. Once you have a live key, inspect a real record (e.g. get_client) to learn the field names.

Error handling

Every tool catches failures and returns an MCP error result rather than crashing the server:

Error: Smart NPV /api/v2/clients/get_client_status -> HTTP 401: {"message":"invalid api_key"}

Common cases:

• Key missing: SMARTNPV_API_KEY is not set.

• Auth failure: HTTP 401/403 (bad or unauthorized key, or a Premium tool on a non-Premium plan).

• Bad arguments: the API returns a 4xx with a message; it is surfaced verbatim.

Troubleshooting

Development

npm install
npm run dev        # run from source with tsx (no build)
npm run build      # compile TypeScript to dist/
npm run typecheck  # type-check only
npm start          # run the built server

Project layout:

src/
  index.ts       MCP server: registers every tool, wires stdio transport
  endpoints.ts   the 32 endpoint definitions (path, method, zod input schema)
  client.ts      HTTP client: GET (query), POST (json body), multipart upload

Adding a tool is one entry in endpoints.ts. The server registers it automatically.

Quick smoke test (lists tools over the MCP protocol):

printf '%s\n' \
 '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}' \
 '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
 '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
 | SMARTNPV_API_KEY=test node dist/index.js

Project status and roadmap

• ✅ All 32 documented endpoints wrapped as tools.

• ✅ Type-checks, builds, and passes an MCP tools/list smoke test.

• ⏳ Not yet live-tested against a real account (needs an API key). Until then, treat response shapes as indicative.

• 🔜 Tighten the free-form params schemas once real field names are confirmed against a live key.

• 🔜 Optional: publish to npm so npx smart-npv-mcp works with no clone.

Contributing

Issues and pull requests welcome. Good first contributions: confirming real field names for the params payloads, adding response examples from a live account, or improving tool descriptions.

License

MIT © 2026 Binyamin Boukaya (BeAi).

Smart NPV is a trademark of its respective owner. This is an independent, unofficial integration.