Loan MCP Server

A production-grade Model Context Protocol (MCP) server for a Loan Management System backed by Microsoft Dataverse. It exposes read/analytics tools that MCP clients (Claude Desktop, Copilot Studio, etc.) can call to look up and report on loan applications.

• Transports: stdio (for Claude Desktop) and Streamable HTTP (for Copilot Studio / remote clients) — same server, same tools, JSON-RPC 2.0 (official @modelcontextprotocol/sdk)

• Auth: Microsoft Entra ID Client Credentials flow (@azure/msal-node)

• Data: Dataverse Web API v9.2 directly (no Power Automate, no connectors)

• Language: TypeScript (strict) on Node.js 22+

Table of contents

• Tools

• Architecture

• Authentication flow

• Dataverse integration

• Prerequisites

• Setup

• Environment variables

• Running locally

• Testing

• Connect to Claude Desktop

• Connect to Copilot Studio

• Example requests & responses

• Error handling

• Troubleshooting

Related MCP server: Vybog MCP Server

Tools

All tools return business-friendly field names — Dataverse logical names are never exposed.

Customer tools

Internal tools

Architecture

                         ┌──────────────────────────────┐
   MCP client            │        index.ts (stdio)      │
 (Claude / Copilot) ◄───►│   JSON-RPC 2.0 over stdio    │
                         └───────────────┬──────────────┘
                                         │
                         ┌───────────────▼──────────────┐
                         │          server.ts           │  composition root (DI)
                         │  wires config → auth →        │
                         │  service → tool registry      │
                         └───────┬───────────────┬───────┘
                                 │               │
                 ┌───────────────▼──┐     ┌──────▼──────────────┐
                 │  tools/*  (12)   │     │  auth/auth.ts       │
                 │  defineTool()    │     │  Entra ID tokens    │
                 │  schemas (zod)   │     │  (MSAL, cached)     │
                 └───────┬──────────┘     └──────┬──────────────┘
                         │                       │ bearer token
                 ┌───────▼───────────────────────▼──────────────┐
                 │        services/dataverseService.ts          │
                 │  executeQuery / finders / choice metadata    │
                 │  Axios (reused) · retry-on-401 · pagination  │
                 └───────┬──────────────────────────────────────┘
                         │  raw records (logical names)
                 ┌───────▼──────────┐     ┌────────────────────┐
                 │  models/loan.ts  │     │  errors/index.ts   │
                 │  mappers +       │     │  AppError + typed  │
                 │  domain logic    │     │  subclasses        │
                 └──────────────────┘     └────────────────────┘

     config/  (env · dataverse names · tool names · documents)   utils/logger.ts (pino → stderr)

Design principles

• Single source of truth for logical names — config/dataverse.ts holds every table/column logical name; models/loan.ts mappers are the only translation point to business fields.

• Repository/service pattern — DataverseService owns all HTTP; tools never build requests. executeQuery() is the single list primitive (with pagination); finders (findLoanByReference, findLoansByPhone, …) compose it.

• Open/closed tools — each tool is a declarative defineTool({...}); the wrapper adds timing, logging and error mapping. Add a tool by listing it in tools/registry.ts.

• Dependency injection — createServer() wires everything and accepts overrides for testing.

• Typed errors — AppError subclasses (AuthenticationError, DataverseError, ValidationError, LoanNotFoundError) → clean MCP results.

• stdout is sacred — it carries only JSON-RPC; all logs go to stderr.

Project structure

src/
├── index.ts                     # Entrypoint: stdio transport + lifecycle
├── http.ts                      # Entrypoint: Streamable HTTP transport + sessions
├── server.ts                    # Composition root (DI) — shared by both entrypoints
├── auth/
│   └── auth.ts                  # EntraAuthProvider (MSAL, cached tokens)
├── config/
│   ├── index.ts                 # Centralized appConfig (validated once)
│   ├── env.ts                   # Env schema + parsing (the only process.env reader)
│   ├── dataverse.ts             # Table/column logical names, statuses, select set
│   ├── tools.ts                 # Canonical tool names
│   └── documents.ts             # Loan-type → required documents mapping
├── errors/
│   └── index.ts                 # AppError hierarchy + codes
├── models/
│   └── loan.ts                  # Loan + projections, mappers, domain functions
├── services/
│   └── dataverseService.ts      # Reusable Web API client
├── tools/
│   ├── shared.ts                # defineTool wrapper + result helpers
│   ├── schemas.ts               # Reusable Zod input fields
│   ├── registry.ts              # List of all tool registrars
│   └── *.ts                     # 12 tool modules
└── utils/
    └── logger.ts                # pino logger (stderr only)

Authentication flow

EntraAuthProvider.getAccessToken()
      │
      ├─ valid cached token (not within 60s of expiry)? ── yes ─► return it
      │
      └─ no ─► MSAL acquireTokenByClientCredential(scope = <DATAVERSE_URL>/.default)
                 │  (concurrent callers coalesce onto one in-flight request)
                 └─► cache token + expiry ─► return it

Every Dataverse request:  Axios request interceptor attaches "Authorization: Bearer <token>".
On HTTP 401:              response interceptor forces one refresh + retries the request once.

• Uses the OAuth 2.0 client-credentials grant (app-only, no user).

• Tokens are cached in-memory and reused until ~1 minute before expiry.

• Secrets are read from the environment only and are redacted from logs.

Dataverse integration

• Talks to the Web API directly: https://<org>.crm.dynamics.com/api/data/v9.2/.

• Reads use $select (business columns), $expand (officer lookup → name), $filter (escaped OData literals) and follow @odata.nextLink pagination.

• Choice/Picklist columns (status, eligibilityStatus, loanType) return integers; labels come from the formatted-value annotation. Status filtering resolves a label to its option value via cached option-set metadata.

• The officer lookup is resolved to a display name via $expand of the navigation property (defaults to systemuser → fullname).

Naming note (schema vs logical): the names in the maker portal (cr174_ReferenceNumber) are schema names. The Web API uses logical names, which are always lowercase (cr174_referencenumber). All logical names live in config/dataverse.ts.

Prerequisites

1. Node.js 22+ and npm.

2. A Microsoft Dataverse environment (e.g. https://yourorg.crm.dynamics.com).

3. A loan applications table (cr174_loanapplics) with the documented columns.

4. Permission to create an Entra ID App Registration and a Dataverse Application User.

Setup

1. Azure App Registration

1. Entra ID portal → App registrations → New registration (loan-mcp-server, single tenant).

2. Copy the Application (client) ID and Directory (tenant) ID.

3. Certificates & secrets → New client secret → copy the secret value.

Client-credentials needs no redirect URI or delegated permissions. Access is granted via the Dataverse Application User below.

2. Application User in Dataverse

1. Power Platform Admin Center → environment → Settings → Users + permissions → Application users → New app user.

2. Add the app by its Application (client) ID.

3. Assign a security role with Read on the loan table (and read on the officer lookup's target table, e.g. User, so the officer name resolves).

3. Required API permissions

The token is scoped to https://yourorg.crm.dynamics.com/.default. No admin-consented Graph permissions are required — the Application User + security role authorize the app. Ensure the role grants at least:

• Read on cr174_loanapplics

• Read on systemuser (to resolve officer names)

• Read access to entity metadata (default for authenticated app users) so status option-set values can be resolved.

4. Environment variables

Copy .env.example to .env and fill in the four required values.

Environment variables

Configuration is validated with Zod at startup; invalid/missing values fail fast with an actionable message.

Running locally

npm install        # install dependencies
npm run build      # compile TypeScript to dist/

# Streamable HTTP transport (default `start`; for Copilot Studio / remote / Azure)
npm start          # node dist/http.js  -> listens on HTTP_PORT (default 3000)
npm run dev:http   # from source with reload

# stdio transport (Claude Desktop launches this as a child process)
npm run start:stdio # node dist/index.js
npm run dev         # from source with reload

npm run typecheck  # type-check without emitting

npm start runs the HTTP server so cloud hosts (Azure App Service) that invoke npm start work with no custom startup command. Claude Desktop launches the stdio entrypoint (dist/index.js) directly, so this doesn't affect it.

Transports

Both expose the identical server, auth, service and 12 tools — only the transport differs. The stdio server has no port (an MCP client launches it and talks over stdin/stdout; stdout is reserved for JSON-RPC). The HTTP server listens on HTTP_PORT and serves:

• POST {MCP_HTTP_PATH} — client→server messages (initialize starts a session)

• GET {MCP_HTTP_PATH} — server→client SSE stream for a session

• DELETE {MCP_HTTP_PATH} — terminate a session

• GET /healthz — liveness probe (unauthenticated)

Sessions are tracked via the mcp-session-id header; the token cache and Axios instance are shared across sessions. Protect the HTTP endpoint with MCP_API_KEY (sent as x-api-key or Authorization: Bearer) — if unset, the endpoint is unauthenticated and a warning is logged.

PowerShell note (Windows): if npm is blocked by execution policy, run Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned, or call npm.cmd.

Testing

An automated MCP client drives every tool against your real environment (reads .env):

npm run build
npm test            # or: npm run test:client

It performs the JSON-RPC handshake, asserts all 12 tools are advertised, calls each one and checks response shapes, and verifies the error paths (LOAN_NOT_FOUND, VALIDATION_ERROR, invalid input). A batch reporter is also provided:

npm run test:batch                       # summary table for a set of references
node scripts/batch-test.mjs LN-XXXX LN-YYYY

Sample inputs can be overridden via env: TEST_REF, TEST_PHONE, TEST_EMAIL, TEST_OFFICER, TEST_STATUS, TEST_LOAN_TYPE.

Connect to Claude Desktop

Edit the config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "loan-management": {
      "command": "node",
      "args": ["C:\\Changes\\Innorve\\loan-mcp-server\\dist\\index.js"]
    }
  }
}

Run npm run build first, then fully restart Claude Desktop. The server reads .env from its own folder; alternatively pass secrets via an "env": { … } block in the config. All 12 tools then appear in the tools menu.

Connect to Copilot Studio

Copilot Studio is cloud-hosted and connects to MCP servers over HTTP (not stdio), so use the Streamable HTTP transport and a reachable URL.

1. Run the HTTP transport with an API key:

   npm run build
   # set MCP_API_KEY (and HTTP_HOST=0.0.0.0 if behind a proxy) in .env, then:
   npm run start:http

2. Expose it with a public HTTPS URL so Copilot Studio's cloud can reach it:

   • Testing: a tunnel to http://localhost:3000 (VS Code dev tunnels, ngrok, …).

   • Production: host on Azure App Service / Container Apps and use its HTTPS URL.

3. Register it in Copilot Studio: your agent → Tools → Add tool → Model Context Protocol, and point it at https://<your-host>/mcp. Supply the MCP_API_KEY as the x-api-key header (or Authorization: Bearer).

4. The server advertises all tools via tools/list, so Copilot Studio discovers them automatically. The tool contract is identical to the Claude Desktop integration.

Security: the HTTP endpoint calls your loan data. Always set MCP_API_KEY, serve over HTTPS (via the tunnel/host), and restrict MCP_CORS_ORIGIN in production.

Verify the HTTP transport locally at any time:

npm run start:http                 # in one terminal
MCP_API_KEY=... npm run test:http  # in another (drives it as a real MCP client)

Example MCP requests & responses

Call GetLoanSummary

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "GetLoanSummary",
    "arguments": { "referenceNumber": "LN-20260708090758" }
  }
}

Response (success) — structuredContent plus a text mirror:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "{ ...json... }" }],
    "structuredContent": {
      "referenceNumber": "LN-20260708090758",
      "applicantName": "Yogeshwara B",
      "applicantEmail": "yogeshwara567@gmail.com",
      "phoneNumber": "8197792301",
      "loanAmount": 15000000,
      "propertyValue": 0,
      "loanType": "Personal Loan",
      "status": "Under Review",
      "eligibilityStatus": "Needs Manual Review",
      "eligibilityRemarks": "Loan amount exceeds automatic approval threshold.",
      "reviewRequired": true,
      "assignedOfficer": "Akshitha S",
      "createdDate": "2026-07-08T09:07:57Z",
      "documentsUploaded": false
    }
  }
}

GetLoanAnalytics (no arguments) →

{
  "totalApplications": 71,
  "pending": 10, "approved": 10, "rejected": 4,
  "underReview": 14, "received": 29,
  "averageLoanAmount": 9625394.68,
  "highestLoanAmount": 53214334,
  "lowestLoanAmount": 33
}

GetOfficerWorkload { "officerName": "Akshitha S" } →

{
  "officerName": "Akshitha S",
  "totalWorkload": 3,
  "pendingReviews": 3,
  "byStatus": { "received": 0, "pending": 0, "underReview": 3, "approved": 0, "rejected": 0, "other": 0 },
  "loans": [ { "referenceNumber": "LN-...", "status": "Under Review", "loanAmount": 50000000, "reviewRequired": true } ]
}

Error result (loan not found) —

{
  "result": {
    "isError": true,
    "content": [{ "type": "text", "text": "{ ...json... }" }],
    "structuredContent": {
      "error": "No loan found with reference number 'LN-000'.",
      "code": "LOAN_NOT_FOUND",
      "retryable": false,
      "httpStatus": 404
    }
  }
}

Error handling

Every failure is a typed AppError mapped to a structured MCP result:

Troubleshooting

License

MIT