LIMU Portal MCP

Model Context Protocol server for LIMU Portal operational and finance data. It supports the original local stdio/MySQL mode and a Vercel HTTP mode that authenticates with LIMU OAuth and calls LIMU Portal APIs.

Exposed Data

• Clients, including editable profile records plus cargo, package, shipment, invoice, payment, order-form, lead, KYC, query, and mobile-account summaries.

• Cargo records, tracking numbers, clients, shipment links, package totals, and cargo logs, with confirmation-gated cargo creation in Vercel HTTP mode.

• Cargo package groups, package units, and stage-check summaries, with confirmation-gated package creation in Vercel HTTP mode.

• Shipments, calendars, status updates, cargo totals, and budget summaries.

• Monthly budgets, detailed budget entries, and controlled purchase scheduling.

• Shipment customs budgets and shipping budgets, including income rows, expense rows, and budget logs.

• Requisitions, requisition items, payment vouchers, voucher items, payment proofs, and controlled approval/payment actions.

• Client profile reports, lead reports, order form reports, import product reports, leave applications, and timesheet reports.

Related MCP server: RiseUp MCP Server

Setup

cd /Applications/XAMPP/xamppfiles/htdocs/limu/mcp
cp .env.example .env
npm install
npm run smoke

Vercel HTTP MCP

The Vercel entrypoint is:

/api/mcp

It requires an OAuth bearer token issued by the LIMU Portal OAuth provider. The remote server validates tokens through:

GET /Api/v1/oauth/userinfo/

Then each tool forwards that same bearer token to the relevant LIMU Portal API endpoint, keeping portal permissions as the source of truth.

The server publishes OAuth Protected Resource Metadata at:

/.well-known/oauth-protected-resource

The portal publishes authorization server metadata and supports dynamic client registration, so Codex can register its temporary local callback automatically. Manual callback registration is not required.

Set this Vercel environment variable:

LIMU_PORTAL_BASE_URL=https://portal.limu.co.mw

Then deploy:

npm run build

Vercel will serve the MCP route over Streamable HTTP through mcp-handler.

Add the deployed server to Codex and authenticate it:

codex mcp add limu_mcp --url https://limu-mcp.vercel.app/api/mcp
codex mcp login limu_mcp

Run npm run smoke:oauth to verify protected-resource metadata and audience checks locally.

Cargo writes through the portal

• Cargo and package creation require the cargo:write OAuth scope plus the employee's Cargo create permission.

• Cargo merge and shipment assignment require cargo:write plus Cargo edit permission.

• Merge and assignment default to dry-run previews. Execution requires an unchanged SHA-256 preview token, explicit confirmation, and a stable idempotency key.

• Merges accept only Created, unassigned cargo owned by one client. Source cargo records are deleted after their related records are moved into the approved primary cargo.

• Shipment assignment accepts only Created, unassigned cargo and changes its status to Booked.

The remote migration currently covers OAuth-protected health/userinfo, clients, cargo, cargo packages, shipments, monthly budgets, budget reports, purchase schedules, imports-and-orders, import-product, leads, client-profile reports, and a controlled QuickBooks accounting slice. The leads report returns conversion, source, segment, tag, and pipeline analytics while enforcing the viewer's portal report permissions. The client-profile report summarizes clients active in a selected cargo-activity period, including demographics, tiers, and relations-officer coverage. Requisition, payment voucher, and leave tools remain registered with explicit "portal endpoint pending" responses until their matching portal endpoints are added.

QuickBooks through the portal

The portal is the sole owner of the QuickBooks OAuth connection and keeps its Intuit tokens in the portal database. The MCP never receives or returns those credentials.

• Read tools require the quickbooks:read OAuth scope and an Accounts, Customs, or Payment Vouchers view permission.

• Invoice, bill, customer-payment, and bill-payment tools require quickbooks:write plus Accounts, Customs, or Payment Vouchers management permission.

• Financial write tools default to dryRun: true; a real post requires both dryRun: false and confirm: true.

• Every post requires a stable sourceReference and idempotencyKey. The portal records a local audit row and sends a matching QuickBooks requestid to prevent accidental duplicate postings.

• Direct journal entries, updates, and deletes are deliberately not exposed.

Local Stdio MCP

Use a least-privilege MySQL user. A read-only user is enough for reporting tools, but write tools need narrowly scoped UPDATE access for Clients, monthly_budget_entry, and leave_applications, INSERT/UPDATE/DELETE access for monthly budget schedule splits, UPDATE/INSERT access for leave logs, requisitions, requisition logs, payment vouchers, and budget spend tables, plus DELETE access for eligible requisitions, requisition items/logs, payment vouchers, voucher items, and voucher proof rows. Write tools require confirm: true; use dryRun: true first to preview the exact proposed change. Client auth secrets, token hashes, KYC link tokens, and government ID numbers are intentionally omitted from client tool responses.

Run

cd /Applications/XAMPP/xamppfiles/htdocs/limu/mcp
npm start

Most MCP clients should launch it over stdio. Example client config:

{
  "mcpServers": {
    "limu-portal": {
      "command": "node",
      "args": [
        "/Applications/XAMPP/xamppfiles/htdocs/limu/mcp/src/server.js"
      ],
      "env": {
        "LIMU_DB_HOST": "127.0.0.1",
        "LIMU_DB_PORT": "3306",
        "LIMU_DB_NAME": "limutradee",
        "LIMU_DB_USER": "root",
        "LIMU_DB_PASSWORD": ""
      }
    }
  }
}

Tools

• limu_health

• limu_get_clients

• limu_get_client

• limu_update_client

• limu_list_cargo

• limu_get_cargo

• limu_create_cargo

• limu_merge_cargo

• limu_assign_cargo_shipment

• limu_sync_cargo_package_count

• limu_get_cargo_action_audit

• limu_list_packages

• limu_get_package

• limu_create_package

• limu_list_shipments

• limu_get_shipment

• limu_get_imports_and_orders_report

• limu_get_import_product_report

• limu_list_monthly_budgets

• limu_get_monthly_budget

• limu_get_budget_report

• limu_list_purchase_schedule

• limu_schedule_budget_purchase

• limu_list_shipment_budgets

• limu_get_shipment_budget

• limu_list_customs_budgets

• limu_get_customs_budget

• limu_list_shipping_budgets

• limu_get_shipping_budget

• limu_list_requisitions

• limu_get_requisition

• limu_review_requisition

• limu_delete_requisition

• limu_list_payment_vouchers

• limu_get_payment_voucher

• limu_review_payment_voucher

• limu_delete_payment_voucher

• limu_mark_payment_voucher_paid

• limu_list_client_profile_reports

• limu_get_client_profile_report

• limu_list_lead_reports

• limu_get_lead_report

• limu_list_order_form_reports

• limu_get_order_form_report

• limu_list_leave_applications

• limu_review_leave_application

• limu_list_timesheet_reports

• limu_list_warehouse_timesheet_reports

All tools return JSON text payloads and list tools enforce a configurable limit cap.