Lerian MCP Server
The Lerian MCP Server is a unified gateway connecting AI assistants (Claude Desktop, Cursor, etc.) to Lerian's portfolio of financial and data products, enabling documentation lookup, guided learning, SDK code generation, live API access, and cross-product workflow orchestration.
Core capabilities via the lerian tool:
Portfolio Discovery (
operation="discover"orproduct="all"): List and compare all supported products — Midaz, Tracer, Flowker, Reporter, Fetcher, Matcher, Underwriter.Documentation (
operation="docs"): Retrieve official docs for any product/topic, with configurable detail levels (summary, detailed, examples-only).Guided Learning (
operation="learn"): Access tutorials and learning paths tailored by experience level (beginner, intermediate, advanced).SDK Code Generation (
operation="sdk"): Generate Go, TypeScript, or JavaScript code examples for specific use cases.Cross-Product Search (
operation="search",product="all"): Search documentation and examples across all products simultaneously.
Live API interaction:
Contract Discovery (
*-discovertools, e.g.midaz-discover): Inspect live resource schemas, actions, parameters, and examples.API Execution (
*-executetools, e.g.midaz-execute): Execute read or mutating API calls; mutations requireconfirmMutation=trueand amutationReasonfor safety and auditability.
Workflow orchestration:
Cross-Product Workflows (
portfolio-workflowtool): Run multi-product workflows (e.g. fetcher-to-reporter) with stateful sessions and step-by-step guidance.
Product endpoints and authentication are configurable via environment variables or other configuration sources.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Lerian MCP Server Show me how to create a workflow in Flowker"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Lerian MCP Server
An MCP gateway for Lerian portfolio discovery, documentation, learning, SDK examples, live product API access, and cross-product workflows.
This server connects MCP clients such as Claude Desktop, Cursor, Windsurf, Continue, and ChatGPT Desktop to the Lerian product portfolio. It gives AI assistants a structured way to discover Lerian products, read official documentation, generate implementation examples, inspect live API contracts, execute configured product APIs, and guide multi-product operational workflows.
Runtime scope: this server is not documentation-only. The unified
leriantool is read-oriented, but product-specific*-executetools can call configured live Lerian APIs. Mutating API calls require explicit confirmation and an audit reason.
2-Minute Setup
Choose your MCP-compatible AI assistant.
Add the server configuration.
Restart the AI app.
Ask: "What can you tell me about Lerian Midaz?"
Claude Desktop
macOS location: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows location: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"lerian": {
"command": "npx",
"args": ["-y", "@lerianstudio/lerian-mcp-server@latest"]
}
}
}Cursor, Windsurf, Continue, ChatGPT Desktop
Add the same MCP server block to your client's MCP configuration:
{
"mcpServers": {
"lerian": {
"command": "npx",
"args": ["-y", "@lerianstudio/lerian-mcp-server@latest"]
}
}
}Related MCP server: natural-docs-mcp
What You Get
Supported Products
Midaz: unified double-entry ledger — organizations, ledgers, accounts, balances, transactions, and CRM behind a single service.
Fetcher: datasource connection, schema discovery, and asynchronous extraction service.
Reporter: template-driven report generation, datasource management, metrics, and artifacts.
Matcher: reconciliation engine for matching Midaz transactions against external systems.
Tracer: transaction validation engine with rules, limits, validations, and auditability.
Flowker: workflow orchestration platform for providers, executors, webhooks, and execution flows.
Underwriter: jurisdiction-aware lending surface for loan products and schedule preview.
All: portfolio-wide discovery, documentation search, and comparison.
Core Capabilities
Portfolio discovery through
lerianwithoperation="discover".Documentation lookup through
lerianwithoperation="docs".Guided learning through
lerianwithoperation="learn".SDK examples through
lerianwithoperation="sdk".Cross-product search through
lerianwithoperation="search".Live API contract discovery through product-specific
*-discovertools.Live API execution through product-specific
*-executetools.Cross-product workflows through
portfolio-workflow.Prompt-based guidance for onboarding, learning, API use, and operational workflows.
Runtime Tool Surface
The server exposes a small core plus live API pairs for each supported product.
Core Tools
lerian: unified portfolio tool for docs, learning, SDK examples, discovery, and search.portfolio-workflow: cross-product workflow discovery, planning, stateful sessions, and step execution.
Live API Tools
midaz-discoverandmidaz-executefetcher-discoverandfetcher-executereporter-discoverandreporter-executematcher-discoverandmatcher-executetracer-discoverandtracer-executeflowker-discoverandflowker-executeunderwriter-discoverandunderwriter-execute
Use the matching *-discover tool before calling a *-execute tool. Discovery returns resources, actions, path parameters, query parameters, body schemas, examples, and execution hints.
The lerian Tool
The lerian tool is the primary read-oriented entry point.
Tool: lerian
Parameters:
product midaz | fetcher | reporter | matcher | tracer | flowker | underwriter | all
operation discover | docs | learn | sdk | search
topic Topic to inspect, learn, or search
language go | typescript | javascript, for SDK examples
useCase Specific implementation scenario for SDK examples
experienceLevel beginner | intermediate | advanced
format summary | detailed | examples-only
includeExamples true | false
maxResults 1-50, for searchExample:
{
"product": "midaz",
"operation": "learn",
"topic": "transactions",
"experienceLevel": "beginner"
}Live API Workflow
Live API access is intentionally two-step.
Inspect the product surface:
{
"intent": "list-resources"
}Inspect a specific action contract:
{
"intent": "describe-action",
"resource": "transactions",
"action": "create"
}Execute with the exact contract returned by discovery:
{
"resource": "transactions",
"action": "create",
"pathParams": {
"organizationId": "...",
"ledgerId": "..."
},
"body": {
"description": "Example transaction"
},
"confirmMutation": true,
"mutationReason": "Create example transaction requested by operator"
}Mutating live API actions require:
confirmMutation: truemutationReasonwith a human-readable audit reason
Cross-Product Workflows
Use portfolio-workflow when the task spans multiple Lerian products.
Current workflows:
fetcher-to-reporter: validate extraction mappings with Fetcher, then generate or inspect Reporter reports.matcher-to-fetcher-to-midaz: configure Matcher reconciliation, use Matcher discovery over Fetcher, and inspect Midaz ledger-side data.
Supported intents:
list-workflowsdescribe-workflowplancreate-sessionget-sessionlist-sessionsexecute-stepexecute-next
Workflow sessions return an opaque sessionToken. Keep it private.
Configuration
The server works immediately for documentation and discovery. Live API execution requires reachable product services and, where applicable, tokens or API keys.
Configuration sources, in priority order:
Command-line
--configor--config-fileEnvironment variables
./lerian-mcp-config.json./midaz-mcp-config.json~/.lerian/mcp-config.json~/.midaz/mcp-config.json~/.config/lerian/mcp-config.json~/.config/midaz/mcp-config.jsonPlatform global config paths
Create or update configuration interactively:
npx -y -p @lerianstudio/lerian-mcp-server@latest lerian-mcp-configMidaz is a single unified ledger service reached through one base URL. Onboarding, accounts, balances, transactions, and CRM are all resources of that one service, so there is exactly one Midaz URL to configure.
Common environment variables:
LERIAN_DOCS_URL=https://docs.lerian.studio
LOG_LEVEL=info
MIDAZ_BASE_URL=http://localhost:3002
MIDAZ_AUTH_TOKEN=...
MIDAZ_API_TIMEOUT=30000
FETCHER_MANAGER_URL=http://localhost:4006
FETCHER_AUTH_TOKEN=...
REPORTER_MANAGER_URL=http://localhost:4005
REPORTER_AUTH_TOKEN=...
MATCHER_BASE_URL=http://localhost:4018
MATCHER_AUTH_TOKEN=...
TRACER_BASE_URL=http://localhost:4020
TRACER_API_KEY=...
FLOWKER_BASE_URL=http://localhost:4021
FLOWKER_AUTH_TOKEN=...
FLOWKER_API_KEY=...
UNDERWRITER_BASE_URL=http://localhost:8080
UNDERWRITER_AUTH_TOKEN=...Migrating to 4.0.0
Breaking change: Midaz configuration. Releases before 4.0.0 expected four separate Midaz URLs, one per legacy service (onboarding, transaction, CRM, ledger). Those variables are gone — they are not read and not accepted. Point MIDAZ_BASE_URL at your unified Midaz ledger instead, and keep MIDAZ_AUTH_TOKEN as is. Nothing else in the configuration changed.
Safety Model
Live execution is opt-in through product-specific
*-executetools.Mutating methods require explicit confirmation and a mutation reason.
Product API base URLs must use
httporhttps.Non-localhost HTTP URLs are rejected; HTTPS is required outside local development.
URLs with embedded credentials are rejected.
Authorization and API-key headers are protected from arbitrary override.
Binary upload and download sizes are bounded by configurable limits.
Secrets are generated and managed locally under
~/.lerian/secrets.jsonwhen needed.
Example Conversations
Portfolio Discovery
You: "What Lerian products can this MCP help with?"
AI: Uses lerian with product="all", operation="discover".
Learning Path
You: "I'm new to Tracer. Teach me how validation rules work."
AI: Uses lerian with product="tracer", operation="learn", topic="rules".
SDK Example
You: "Show me Go code for creating a Midaz ledger."
AI: Uses lerian with product="midaz", operation="sdk", language="go".
Live API Contract Discovery
You: "Inspect the contract for creating a Reporter template."
AI: Uses reporter-discover before any reporter-execute call.
Cross-Product Workflow
You: "Guide me through validating Fetcher mappings before generating a report."
AI: Uses portfolio-workflow with workflow="fetcher-to-reporter".
Development
Requires Node.js >=20.19.0.
npm ci
npm run build
npm testUseful scripts:
npm run dev: run the TypeScript entrypoint withts-node.npm run build: compile todist/and mark binaries executable.npm run lint: run ESLint.npm run typecheck: run TypeScript without emitting files.npm test: run Node tests plus the basic server test.npm run docs: generate TypeDoc output intodocs/.
Documentation
Package Information
npm package:
@lerianstudio/lerian-mcp-server— the npm page and the GitHub releases carry the current version and changelog.Runtime: Node.js ESM
Transport: stdio only
License: Apache-2.0
Repository: github.com/lerianstudio/lerian-mcp-server
Architecture Summary
MCP Client
-> stdio transport
-> MCP server runtime
-> core tools and prompts
-> product adapters
-> product routers and schema registries
-> configured Lerian product APIsPrimary layers:
Transport: MCP JSON-RPC over stdio.
Server bootstrap: security, secrets, docs manifest, logging, client detection.
Core tools:
lerianandportfolio-workflow.Product adapters: discover/execute pairs for supported products.
Schema registries: resource/action contracts for API surfaces.
HTTP execution: validated URL construction, request execution, response parsing, and error classification.
Workflow orchestration: guided, stateful multi-product flows.
Troubleshooting
Server Not Starting
Check Node.js version:
node --versionRun manually:
npx -y @lerianstudio/lerian-mcp-server@latestCheck local secrets:
ls -la ~/.lerian/secrets.jsonLive API Calls Failing
Use the product
*-discovertool first.Verify the relevant base URL and token/API key are configured.
Confirm non-local remote URLs use HTTPS.
For mutations, include
confirmMutation=trueandmutationReason.Check whether the target product service is reachable from the MCP runtime.
Tool Not Responding In The Client
Restart the MCP client after configuration changes.
Confirm MCP is enabled in the client.
Enable logging with
LOG_LEVEL=debugif needed.Check
./logs/when logging is enabled.
Available Tools
16 toolsfetcher-discoverARead-onlyIdempotent
Discover Fetcher manager resources, actions, and execution contracts. Use this before fetcher-execute to inspect path params, required headers like organizationId/productName, body shapes, and supported migration/fetcher job operations.
Inputs: intent (required), query, action, resource, +1 more.
fetcher-executeADestructive
Execute Fetcher manager API actions. Use fetcher-discover first to inspect the required organizationId/productName context, path params, query params, and request body shape before calling this tool.
Inputs: action (required), resource (required), body, pathParams, +5 more.
flowker-discoverARead-onlyIdempotent
Discover Flowker API resources, actions, and execution contracts. Use this before flowker-execute to inspect workflow definitions, execution start requirements, provider and executor configuration payloads, audit filters, dashboard summaries, and webhook method/path behavior.
Inputs: intent (required), query, action, resource, +1 more.
flowker-executeADestructive
Execute Flowker API actions. Use flowker-discover first to inspect auth expectations, Idempotency-Key requirements for workflow execution start, provider and executor configuration payloads, and webhook method/path behavior.
Inputs: action (required), resource (required), body, headers, +4 more.
lerianARead-onlyIdempotent
Unified portfolio tool for Lerian products. Discover supported products and current MCP coverage, access documentation and learning resources, generate SDK examples, and search across the portfolio. Live API execution is available through product-specific tools for Midaz, Fetcher, Reporter, Matcher, Tracer, Flowker, and Underwriter, with cross-product workflow support available via portfolio-workflow.
Inputs: product (required), operation (required), topic, format, +5 more.
matcher-discoverARead-onlyIdempotent
Discover Matcher API resources, actions, and execution contracts. The current live slice covers contexts, sources, field maps, discovery-over-Fetcher endpoints, matching runs, exceptions, disputes, governance, reporting, and system operations. Use this before matcher-execute to inspect headers, path params, query filters, payload requirements, and export behavior.
Inputs: intent (required), query, action, resource, +1 more.
matcher-executeADestructive
Execute Matcher API actions. The current live slice covers contexts, sources, field maps, discovery-over-Fetcher endpoints, matching runs, exceptions, disputes, governance, reporting, and system operations. Use matcher-discover first to inspect payloads, required headers, and reporting export behavior.
Inputs: action (required), resource (required), body, headers, +4 more.
midaz-discoverARead-onlyIdempotent
Discover Midaz API resources, actions, and schemas. Use this BEFORE calling midaz-execute to find the right resource+action and understand required parameters. Supports listing all resources, describing specific resources/actions, searching, and filtering by component.
Inputs: intent (required), query, action, resource, +1 more.
midaz-executeADestructive
Execute Midaz API operations. Use midaz-discover first to find the right resource+action and required parameters, then call this tool to execute. Supports all CRUD operations across organizations, ledgers, assets, accounts, transactions, balances, holders, aliases, and more.
Inputs: action (required), resource (required), body, pathParams, +3 more.
portfolio-workflowADestructive
Cross-product workflow tool for orchestrating guided steps across Lerian products. Supports workflow discovery, readiness planning, stateful workflow sessions, step execution, and execute-next progression. Implemented workflows include fetcher-to-reporter and matcher-to-fetcher-to-midaz.
Inputs: intent (required), step, input, limit, +4 more.
reporter-discoverARead-onlyIdempotent
Discover Reporter manager resources, actions, and execution contracts. Use this before reporter-execute to inspect multipart requirements for templates, request headers like X-Idempotency, report download behavior, and the available template/report/deadline/datasource endpoints.
Inputs: intent (required), query, action, resource, +1 more.
reporter-executeADestructive
Execute Reporter manager API actions. Use reporter-discover first to inspect multipart requirements for template upload/update, request headers like X-Idempotency, and binary download behavior for report artifacts.
Inputs: action (required), resource (required), body, headers, +5 more.
tracer-discoverARead-onlyIdempotent
Discover Tracer API resources, actions, and execution contracts. Use this before tracer-execute to inspect rule/limit operations, validation payloads, audit investigation filters, and operational endpoints.
Inputs: intent (required), query, action, resource, +1 more.
tracer-executeBDestructive
Execute Tracer API actions. Use tracer-discover first to inspect rule/limit transitions, validation request bodies, audit filters, and operational endpoints before calling this tool.
Inputs: action (required), resource (required), body, headers, +4 more.
underwriter-discoverARead-onlyIdempotent
Discover Underwriter API resources, actions, and execution contracts. Use this before underwriter-execute to inspect jurisdiction discovery, loan product lifecycle actions, schedule preview payloads, and the example endpoints currently mounted by the service.
Inputs: intent (required), query, action, resource, +1 more.
underwriter-executeADestructive
Execute Underwriter API actions. Use underwriter-discover first to inspect bearer-auth requirements for protected routes, loan product path/query contracts, and the schedule preview payload where decimal amounts are encoded as strings.
Inputs: action (required), resource (required), body, headers, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Each product-specific tool clearly targets a distinct product, and the discover/execute split is unambiguous. The two meta tools (lerian and portfolio-workflow) serve separate discovery and cross-product workflow purposes, so there is no overlap or confusion between any tools.
The 14 product tools follow a highly consistent <product>-discover/<product>-execute pattern. However, the 'lerian' and 'portfolio-workflow' tools deviate from this convention, introducing a minor inconsistency that prevents a perfect score.
With 16 tools, the count is slightly above the typical 3-15 range, but every tool is necessary to cover seven distinct products, each requiring discovery and execution, plus two meta tools. The size is justified by the multi-product scope.
The tool set provides complete coverage for each product with both discovery and execution capabilities, including full CRUD operations. The addition of a unified documentation tool and a cross-product workflow tool ensures no dead ends and covers the entire lifecycle from exploration to execution.
Maintenance
Related MCP Connectors
Docsy gives AI assistants current, version-specific documentation for libraries, frameworks and SDKs. Resolve library IDs and versions, then search and fetch focused official documentation with original source links using five read-only MCP tools. Hosted Streamable HTTP with OAuth 2.1 sign-in.
Gemmein docs, API reference, error explainers and a live integration check for coding agents.
Versioned documentation registry and semantic search for AI tools and coding assistants.
Publish your API docs so AI assistants can look up endpoints and call your API correctly.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to automatically create, update, and publish API documentation through Theneo's platform. Supports OpenAPI specs, Postman collections, AI-powered description generation, and natural language interactions for seamless documentation workflows.MIT
- AlicenseAqualityDmaintenanceProvides read-only tools to search, read, and look up Natural API documentation from an AI agent, enabling documentation lookup without credentials.4MIT
- FlicenseNot gradedqualityDmaintenanceProvides AI assistants with live, searchable documentation for any programming library, eliminating hallucinated APIs by returning current, structured API references.-
- AlicenseAqualityBmaintenanceEnables AI assistants to search API documentation, retrieve endpoint details, get SDK snippets, and check changelogs from an OpenAPI spec.7104 npm4MIT