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 lerian tool is read-oriented, but product-specific *-execute tools can call configured live Lerian APIs. Mutating API calls require explicit confirmation and an audit reason.

---

2-Minute Setup

1. Choose your MCP-compatible AI assistant.
2. Add the server configuration.
3. Restart the AI app.
4. 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"]
    }
  }
}

---

What You Get

Supported Products

• Midaz: financial ledger platform with onboarding, balances, transactions, CRM, and ledger services.
• 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 lerian with operation="discover".
• Documentation lookup through lerian with operation="docs".
• Guided learning through lerian with operation="learn".
• SDK examples through lerian with operation="sdk".
• Cross-product search through lerian with operation="search".
• Live API contract discovery through product-specific *-discover tools.
• Live API execution through product-specific *-execute tools.
• 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-discover and midaz-execute
• fetcher-discover and fetcher-execute
• reporter-discover and reporter-execute
• matcher-discover and matcher-execute
• tracer-discover and tracer-execute
• flowker-discover and flowker-execute
• underwriter-discover and underwriter-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 search

Example:

{
  "product": "midaz",
  "operation": "learn",
  "topic": "transactions",
  "experienceLevel": "beginner"
}

---

Live API Workflow

Live API access is intentionally two-step.

1. Inspect the product surface:

{
  "intent": "list-resources"
}

2. Inspect a specific action contract:

{
  "intent": "describe-action",
  "resource": "transactions",
  "action": "create"
}

3. 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: true
• mutationReason with 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-workflows
• describe-workflow
• plan
• create-session
• get-session
• list-sessions
• execute-step
• execute-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 --config or --config-file
• Environment 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.json
• Platform global config paths

Create or update configuration interactively:

npx -y -p @lerianstudio/lerian-mcp-server@latest lerian-mcp-config

Common environment variables:

LERIAN_DOCS_URL=https://docs.lerian.studio
LOG_LEVEL=info

MIDAZ_ONBOARDING_URL=http://localhost:3000
MIDAZ_TRANSACTION_URL=http://localhost:3001
MIDAZ_CRM_URL=http://localhost:3002
MIDAZ_LEDGER_URL=http://localhost:3003
MIDAZ_AUTH_TOKEN=...

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=...

---

Safety Model

• Live execution is opt-in through product-specific *-execute tools.
• Mutating methods require explicit confirmation and a mutation reason.
• Product API base URLs must use http or https.
• 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.json when 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 test

Useful scripts:

• npm run dev: run the TypeScript entrypoint with ts-node.
• npm run build: compile to dist/ 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 into docs/.

---

Documentation

• Full Documentation
• Learning Paths
• SDK Reference
• Troubleshooting
• Media and Diagram Index
• Agent Instructions

---

Package Information

• npm package: @lerianstudio/lerian-mcp-server
• Current package version: 3.4.0
• Runtime: Node.js ESM
• MCP SDK: @modelcontextprotocol/sdk
• License: Apache-2.0
• Repository: github.com/lerianstudio/lerian-mcp-server

---

Architecture Summary

MCP Client
  -> stdio transport
  -> McpServer from @modelcontextprotocol/sdk
  -> core tools and prompts
  -> product adapters
  -> product routers and schema registries
  -> configured Lerian product APIs

Primary layers:

1. Transport: MCP JSON-RPC over stdio.
2. Server bootstrap: security, secrets, docs manifest, logging, client detection.
3. Core tools: lerian and portfolio-workflow.
4. Product adapters: discover/execute pairs for supported products.
5. Schema registries: resource/action contracts for API surfaces.
6. HTTP execution: validated URL construction, request execution, response parsing, and error classification.
7. Workflow orchestration: guided, stateful multi-product flows.

---

Troubleshooting

Server Not Starting

Check Node.js version:

node --version

Run manually:

npx -y @lerianstudio/lerian-mcp-server@latest

Check local secrets:

ls -la ~/.lerian/secrets.json

Live API Calls Failing

• Use the product *-discover tool first.
• Verify the relevant base URL and token/API key are configured.
• Confirm non-local remote URLs use HTTPS.
• For mutations, include confirmMutation=true and mutationReason.
• 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=debug if needed.
• Check ./logs/ when logging is enabled.