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

---

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 two environment variables:

Variable	Required	Default	Notes
SMARTNPV_API_KEY	for API calls	(none)	Your key from the extended subscription. The server still starts and lists its tools without it, but every call will error until it is set.
SMARTNPV_BASE_URL	no	https://www.snpv.co.il	The API host. Note: api.snpv.co.il only serves the docs; the API itself is on www.snpv.co.il. Confirm the production base with Smart if unsure.

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.

<details> <summary><b>Claude Desktop</b> (<code>claude_desktop_config.json</code>)</summary>

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

</details>

<details> <summary><b>Cursor</b> (<code>.cursor/mcp.json</code>)</summary>

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

</details>

<details> <summary><b>From source</b> (any client, absolute path to the build)</summary>

{
  "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"
      }
    }
  }
}

</details>

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.

Request type	Where api_key goes
GET tools	query parameter
POST tools	field in the JSON body
Upload tools	multipart form field

Tool reference (32 tools)

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

<details open> <summary><b>Clients</b> (8 tools)</summary>

Tool	Arguments	What it does
list_clients	limit, offset, range_type, from (DD/MM/YYYY), until, lead (bool), reference	List clients or leads, paged and date-filtered.
get_client	type (uuid|phone), uuid, phone	Fetch one client by uuid or phone.
get_client_documentations	uuid	List the documents attached to a client.
create_client	params	Create a client (fields inside params).
update_client	uuid, params	Update a client.
delete_client	uuid	Delete a client (irreversible).
add_documentation	uuid, params	Add a documentation record.
upload_document	uuid, file_name, file_path	Upload a PDF/PNG/JPG file to a client.

</details>

<details> <summary><b>Status</b> (3 tools)</summary>

Tool	Arguments	What it does
get_client_status	uuid	Current status/stage of a client. Core for pipeline monitoring.
get_status_list	(none)	The status/stage definitions in the account.
add_status	params	Add/set a status on a client.

</details>

<details> <summary><b>Simulation</b> (5 tools)</summary>

Tool	Arguments	What it does
get_client_simulations	uuid	List a client's mortgage simulations.
get_simulation	uuid, simulation_uuid	Fetch a specific simulation.
add_simulation	uuid, simulation_name, note, current_mix_toolbar, current_mix, mixes	Add a mortgage mix.
delete_simulation	uuid	Delete a simulation.
calc_simulation (Premium)	request	Run the reform/recalculation engine.

</details>

<details> <summary><b>Payments</b> (3 tools)</summary>

Tool	Arguments	What it does
get_payments	uuid	List a client's payments.
add_payment	uuid, params	Record a payment (e.g. a retainer).
update_payment	payment_uuid, params	Update a payment.

</details>

<details> <summary><b>Contacts</b> (4 tools)</summary>

Tool	Arguments	What it does
get_contact_groups	(none)	List contact groups.
get_contacts	(none)	List contacts (bankers, appraisers, etc.).
add_contact	params	Add a contact.
add_contact_group	params	Add a contact group.

</details>

<details> <summary><b>Products, Networks, Services, Data</b> (9 tools)</summary>

Tool	Arguments	What it does
create_product	params	Create a product.
get_sources (Premium)	(none)	List lead sources / networks.
add_source (Premium)	params	Add a lead source.
update_source (Premium)	params	Update a lead source.
balance_report_parsing (Premium)	bank_id, file_path	Upload a bank balance-report PDF for parsing.
get_banks (Premium)	(none)	Banks supported by the balance-report service.
check_bank_availability (Premium)	bank_id	Is a bank supported by the service.
approval_in_principle_scanning (Premium)	bank_id, file_path	Upload an approval-in-principle PDF for scanning.
get_cities	(none)	Reference list of cities.

</details>

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

Symptom	Likely cause / fix
Every call returns "api_key is not set"	SMARTNPV_API_KEY is not in the server's env. Put it in your MCP client config's env.
401 / 403 on every call	Wrong key, or API access not enabled on your subscription.
404 on all calls	Wrong base URL. Ensure it is https://www.snpv.co.il (not api.snpv.co.il).
A specific tool 403s	It is a Premium tool and your plan is not Premium.
Tools do not appear in the client	Restart the client after editing the config; check the command/path is correct.
Upload fails	Ensure file_path is an absolute path the server process can read.

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.