Lending

A small Node/TypeScript MCP server that lets a user start an iwoca business finance application entirely from inside a ChatGPT conversation.

The server exposes three tools over the Model Context Protocol's Streamable HTTP transport so it can be installed as a ChatGPT MCP app:

Tool	Purpose
draft_application	Validate the applicant's details and store a draft row. Returns a draft ID and a human-readable summary.
submit_application	Promote a draft to submitted, mint a mock IW-100001-style reference and return a secure (mock) upload URL.
get_application_status	Look up the current status for a reference. Auto-progresses Submitted → Under Review → Documents Requested over time to make the demo feel alive.

⚠️ This is a proof of concept. It performs no underwriting, KYC, AML, credit, document, or CRM integration. The upload URL is a placeholder on demo.iwoca.app.

ChatGPT demo (visual walkthrough)

A self-contained browser demo shows what the product experience should look like inside ChatGPT — conversational application, inline iwoca widgets, and status tracking. No server or API keys required.

npm run demo

Open http://localhost:3456. The chat starts blank — try something like "I need funding for my small business" to begin.

Tech stack

• Node.js ≥ 20, TypeScript (ESM)
• @modelcontextprotocol/sdk (Streamable HTTP server transport)
• Fastify + @fastify/cors
• Zod for input validation
• better-sqlite3 for persistence (single applications table)
• Optional Docker image

Project layout

iwoca-poc/
  src/
    mcp.ts                       # Shared MCP server factory + tool registration
    server.ts                    # HTTP entry point (Streamable HTTP, for ChatGPT)
    stdio.ts                     # stdio entry point (for the MCP Inspector)
    database.ts                  # SQLite schema and connection
    validation.ts                # Zod schemas + error formatter
    tools/
      draftApplication.ts
      submitApplication.ts
      getApplicationStatus.ts
    services/
      applicationService.ts      # Draft / submit / status logic
  package.json
  tsconfig.json
  Dockerfile
  demo/
    index.html                   # ChatGPT-style visual demo
  README.md

Running locally

npm install
npm run dev        # tsx watch, hot-reload
# or
npm run build && npm start

The server listens on http://0.0.0.0:3000 by default. Environment variables:

Variable	Default	Description
PORT	3000	HTTP port.
HOST	0.0.0.0	Bind address.
IWOCA_DB_PATH	data/iwoca.sqlite	SQLite file path (parent dir auto-created).
LOG_LEVEL	info	Fastify log level.

Test it with the MCP Inspector (recommended)

The fastest way to exercise the tools — no ChatGPT account or public URL needed. The MCP Inspector is a local web UI that connects to the server and lets you call each tool by hand.

npm install
npm run inspector

npm run inspector builds the project and launches the Inspector pointed at the stdio entry point (node dist/stdio.js) — it spawns the server for you, so there's nothing else to start. The command prints a URL (with a pre-filled auth token); open it in your browser, click Connect, then walk the flow:

1. Open the Tools tab and click List Tools — you should see draft_application, submit_application, get_application_status.
2. Run draft_application with the applicant fields → copy the returned draft_id.
3. Run submit_application with that draft_id and confirmed: true → note the IW-##### reference and the secure upload URL.
4. Run get_application_status with that reference to see the status (and, after ~30s between checks, the automatic progression).

Prefer a manual stdio session without the UI? npm run dev:stdio runs the stdio server directly so you can pipe newline-delimited JSON-RPC into it.

Endpoints

• POST /mcp — JSON-RPC requests (MCP Streamable HTTP).
• GET /mcp — SSE stream for server → client messages (per session).
• DELETE /mcp — Tear down a session.
• GET /healthz — Liveness probe; returns server name, version, and tool list.

The transport requires the standard MCP headers:

• Accept: application/json, text/event-stream
• Mcp-Session-Id: <session-id> after the first initialize call.

Docker

docker build -t iwoca-mcp .
docker run -p 3000:3000 -v $PWD/data:/app/data iwoca-mcp

Smoke test (curl)

# 1. Initialise a session — capture the mcp-session-id response header.
curl -i -X POST http://localhost:3000/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},
                 "clientInfo":{"name":"curl","version":"0"}}}'

SID=<paste mcp-session-id>

# 2. Send the initialized notification.
curl -X POST http://localhost:3000/mcp \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SID" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# 3. Draft an application.
curl -X POST http://localhost:3000/mcp \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
        "name":"draft_application","arguments":{
          "first_name":"Jane","last_name":"Doe",
          "company_name":"Acme Bakery Ltd",
          "amount_requested":50000,"annual_turnover":350000,
          "use_of_funds":"Buy a new oven and hire 2 staff",
          "funds_duration":"12 months",
          "email":"[email protected]","phone":"+44 7700 900123"}}}'

# 4. Submit using the draft_id from the previous response.
curl -X POST http://localhost:3000/mcp \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SID" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
        "name":"submit_application","arguments":{
          "draft_id":"<draft_id>","confirmed":true}}}'

# 5. Check status with the returned IW-#### reference.
curl -X POST http://localhost:3000/mcp \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SID" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{
        "name":"get_application_status","arguments":{
          "application_reference":"IW-100001"}}}'

Connecting from ChatGPT

In ChatGPT, add the MCP server's public URL (https://<your-host>/mcp) as a Streamable HTTP MCP connector. ChatGPT will then naturally:

1. Ask the user for any missing application fields.
2. Call draft_application with the collected fields.
3. Read the returned summary back to the user.
4. Ask for confirmation.
5. Call submit_application with confirmed: true.
6. Share the IW-##### reference and the secure upload link.
7. Call get_application_status on demand to report progress.

To expose a local instance for testing, tunnel it (e.g. ngrok http 3000) and use the public URL.

Data model

A single applications table:

column	type	notes
id	TEXT (UUID)	primary key, the draft_id
reference	TEXT	IW-100001+, set on submission
status	TEXT	draft → submitted → under_review → documents_requested
first_name, last_name, company_name	TEXT
amount_requested, annual_turnover	REAL	GBP
use_of_funds, funds_duration	TEXT
email, phone	TEXT
created_at, updated_at	TEXT	ISO-8601

Validation rules

Enforced by Zod in src/validation.ts:

• All fields required and non-empty.
• amount_requested > 0 and ≤ £1,000,000.
• annual_turnover numeric and ≥ 0.
• email must be a valid address.
• phone must match ^\+?[0-9 ()\-]{7,20}$.
• submit_application requires confirmed: true (a literal true, not just truthy).

Validation failures are returned as isError: true tool results with a bullet list of issues so the model can ask the user for the missing/invalid fields.

What's deliberately out of scope

No underwriting, credit scoring, KYC/AML, Open Banking, document processing, OCR, email delivery, CRM integration, production iwoca APIs, authentication, dashboards, or notifications. The goal is purely to demonstrate the conversational application flow end-to-end inside ChatGPT.