Vybog Server

A standalone Model Context Protocol (MCP) server for the Fund Tracking System. This server enables agents to create, read, update, and delete lending business data (entities, borrowers, investors, deals, referrals) through a standardized interface.

Features

• Entity Management for borrower entities used by borrowers and deals
• Full CRUD Operations on all resources (Entities, Borrowers, Investors, Deals, Referrals)
• Bulk Operations for creating multiple records at once
• Authentication using admin credentials
• MCP Protocol for seamless integration with Claude and other AI agents
• Error Handling and validation

Installation

1. Navigate to the server directory:

cd /Users/chiragpatel/Projects/vybog/fts-mcp

2. Install dependencies:

npm install

3. Create .env file from template:

cp .env.example .env

4. Configure your environment:

BACKEND_URL=http://localhost:2000
[email protected]
ADMIN_PASSWORD=admin123

Running the Server

Development mode (with auto-reload):

npm run dev

Production mode:

npm start

The server communicates via stdio and is designed to be invoked by Claude or other MCP clients.

Cloud AI Agent (OpenAI-Compatible + MCP)

You can run this agent using a cloud LLM with an OpenAI-compatible API.

1) Configure cloud LLM credentials

Set environment variables:

export OPENAI_API_KEY=your_api_key_here
export OPENAI_MODEL=gpt-4o-mini
# Optional custom endpoint
# export OPENAI_BASE_URL=https://api.openai.com/v1

2) Configure backend credentials

Set up .env in this project (same values used by MCP server):

BACKEND_URL=http://localhost:2000
[email protected]
ADMIN_PASSWORD=admin123

3) Run the agent

Interactive mode:

npm run agent

One-shot mode:

npm run agent -- "list all investors"

Optional environment variables:

• OPENAI_API_KEY (required)
• OPENAI_MODEL (default: gpt-4o-mini)
• OPENAI_BASE_URL (default: https://api.openai.com/v1)
• OPENAI_TIMEOUT_MS (default: 45000)

Example:

OPENAI_API_KEY=your_api_key OPENAI_MODEL=gpt-4o-mini npm run agent

4) What it does

The agent runs from src/agent and connects to src/index.js through MCP stdio. It plans tool calls from natural language and executes CRUD using existing tools such as:

• create_borrower, list_borrowers, get_borrower, update_borrower, delete_borrower
• create_investor, list_investors, get_investor, update_investor, delete_investor
• create_deal, list_deals, get_deal, update_deal, delete_deal
• create_referral, list_referrals, get_referral, update_referral, delete_referral
• create_entity, list_entities, get_entity, update_entity
• add_invest_amount, link_investor_to_deal
• replace_investor_on_deal
• add_origination_fee_to_deal, add_monthly_interest_to_deal, add_daily_interest_to_deal
• add_borrower_payment_to_deal, add_borrower_disbursement_to_deal, add_referral_to_deal

Available Tools

Borrowers

• create_borrower - Create a new borrower
• list_borrowers - List all borrowers with pagination
• get_borrower - Get borrower details
• update_borrower - Update borrower information
• delete_borrower - Delete a borrower
• bulk_create_borrowers - Create multiple borrowers at once

Entities

• create_entity - Create a borrower entity
• list_entities - List all borrower entities
• list_unmapped_entities - List entities not currently mapped to borrowers or deals
• get_entity - Get entity details
• update_entity - Update entity information

Investors

• create_investor - Create a new investor
• list_investors - List all investors
• get_investor - Get investor details
• update_investor - Update investor information
• delete_investor - Delete an investor
• bulk_create_investors - Create multiple investors at once

Deals

• create_deal - Create a new lending deal
• list_deals - List all deals (filterable by status)
• get_deal - Get deal details
• get_deal_financial_summary - Get Financial Summary metrics for a deal (same section as deal view)
• get_deal_payoff_calculation - Get Payoff Calculator values for a deal
• update_deal - Update deal information
• delete_deal - Delete a deal
• link_investor_to_deal - Link an investor to a deal with amount, interest, and start date
• replace_investor_on_deal - Close out existing investor and replace with new investor funding
• add_origination_fee_to_deal - Add origination fee schedule to a deal
• add_monthly_interest_to_deal - Add monthly interest schedule to a deal
• add_daily_interest_to_deal - Add daily interest schedule to a deal
• add_borrower_payment_to_deal - Add a borrower payment received on a deal
• add_borrower_disbursement_to_deal - Add borrower disbursement (Holdback, Initial Amount, Topoff)
• add_referral_to_deal - Add referral detail to a deal using amount or rate

Referrals

• create_referral - Create a referral
• list_referrals - List all referrals
• get_referral - Get referral details
• update_referral - Update referral
• delete_referral - Delete a referral

Usage Examples

When invoked by Claude, you can ask it to:

"Create a borrower entity for TechStart Solutions LLC"
"Add investor William Scott to deal Aerospace dynamic"
"Add 100 billion contribution amount to Grace Evans"
"Link investor William Scott to deal Aerospace Dynamics with invested amount 250000, interest 8%, start date 2026-06-01"
"On deal Aerospace Dynamics, close out investor William Scott and replace with Sophia Martinez for amount 250000, start date 2026-07-01"
"On deal AeroSpace Dynamics R&D, close out Grace Evans and replace with Sophia Turner for amount 2000000, start date 2026-05-25"
"Replace Grace Evans with Sophia Turner on deal AeroSpace Dynamics R&D"  # agent should ask for amount and start date
"Add referral Maya Singh to deal Aerospace Dynamics at 6% rate"
"Add referral Maya Singh to deal Aerospace Dynamics with 15000 amount"
"Add borrower payment received on deal Aerospace Dynamics: amount 25000, payment type partial, date 2026-05-25"
"Add borrower disbursement to deal Aerospace Dynamics: target date 2026-06-15, type Holdback, amount 50000"
"Add borrower disbursement to deal Aerospace Dynamics: target date 2026-06-20, type Topoff, amount 25000"
"Add origination fee 8% to deal Aerospace Dynamics"
"Add monthly interest 1.5% to deal Aerospace Dynamics"
"Add monthly interest to deal Aerospace Dynamics"  # agent should ask for interest rate
"Add daily interest 12% APR to deal Aerospace Dynamics"
"Add daily interest to deal Aerospace Dynamics"  # agent should ask for interest rate
"Show financial summary for deal AeroSpace Dynamics R&D"
"Give me summary on deal AeroSpace Dynamics R&D"
"Get financial summary for deal id 83"
"Give me the payoff calculation on deal AeroSpace Dynamics R&D"
"Show payoff calculator values for deal id 83"
"List all active deals"
"Create a new deal between borrower XYZ and investor ABC"
"Update the status of deal 123 to completed"

For deal payment/schedule actions, the agent now validates required values before execution:

• Link investor to deal: invested amount, interest %, and start date
• Replace investor on deal: existing investor name, replacement investor name, amount, and start date (replacement investor must have sufficient available balance for the requested amount)
• Deal financial summary: deal name or deal id
• Deal payoff calculation: deal name or deal id
• Add origination fee: split interest value
• Add monthly interest: interest rate %
• Add daily interest: interest rate %
• Add borrower payment: amount, payment type, and date (YYYY-MM-DD)
• Add borrower disbursement: target date, disbursement type (Holdback, Initial Amount, Topoff), and amount (Topoff is normalized to backend type Topup)
• Add referral: referral name and either referral amount or interest rate

Seeding

The MCP seed script now creates entities first, then creates borrowers and links each borrower to its matching entity ID when available.

Run it with:

npm run seed

Seeded data currently includes 10 entities, 10 borrowers, 10 investors, 10 deals, and 10 referrals.

Architecture

vybog-mcp-server/
├── src/
│   ├── index.js           # Main MCP server implementation
│   └── api-client.js      # HTTP client for backend API
├── package.json
├── .env.example
└── README.md

Backend Dependencies

This MCP server requires the fts-be backend service to be running:

1. Start the backend:

cd /Users/chiragpatel/Projects/vybog/fts-be
npm run dev

2. Ensure MySQL is running (or start Docker container):

docker start mysql-vybog

If Docker container doesn't exist, create it:

docker run --name mysql-vybog -e MYSQL_ROOT_PASSWORD=root -e MYSQL_DATABASE=vybog_db -p 3306:3306 -d mysql:8.0

Integration with Claude

To use this MCP server with Claude in VS Code:

1. Configure the MCP server connection in VS Code settings
2. Point to this server's src/index.js
3. Provide environment variables via .env

See: https://modelcontextprotocol.io/

Error Handling

The server includes comprehensive error handling:

• Authentication failures are caught and reported
• API errors from the backend are passed through with context
• Bulk operations report partial success/failure

Development Notes

• The server uses stdio for MCP communication (stdin/stdout)
• JWT tokens are automatically obtained and refreshed
• All operations require admin authentication
• The API client is a singleton pattern for token reuse
• Entity tools map to the backend borrower entity routes under /api/v2/borrower-entity