Lerian MCP connects your AI assistant directly to the Midaz ecosystem. Whether you're using ChatGPT, Claude, Cursor, Windsurf, or another compatible client, this server gives your Large Language Model (LLM) secure, real-time access to Midaz documentation, APIs, and even local services.

It's like giving your assistant insider knowledge—so it can read the docs, generate code, run actions, and help you move faster.

What is MCP?

MCP stands for Model Context Protocol. Think of it as Bluetooth for LLMs: it's how your AI learns what tools it can use, how your system works, and what questions to ask to get the job done.

Lerian MCP teaches your assistant to:

• Understand documentation, architecture, and SDKs
• Use APIs through built-in tools
• Prompt itself intelligently with follow-up questions

Once connected, your assistant becomes context-aware and capable of action.

Why use Lerian MCP?

Lerian MCP transforms your AI assistant into a productive development companion. It helps you:

• Search Midaz documentation with natural language
• Call local Midaz APIs using tools (not just static text)
• Understand Midaz's architecture, endpoints, and SDKs
• Generate code, troubleshoot issues, and automate setup
• Keep everything local and explicitly permissioned

Whether you're building new integrations or supporting production systems, this plugin provides your LLM with the necessary context, safely and instantly.

Built for security

Security is baked into every step. Lerian MCP:

• Runs entirely on your machine
• Has **read-only **access by default
• Requires explicit user approval before writing data
• Needs no API keys for local setup
• Is open source and auditable

Your data stays where it belongs, under your control.

What can your assistant do?

Once connected, your assistant can interact with your Midaz environment as if it has already read the documentation.

It can:

• Explain how Midaz concepts work
• Generate code for real-world tasks (e.g., create an organization)
• Search and summarize API endpoints
• Help debug integration issues
• Explore the architecture and available SDKs
• Run pre-configured tools to call your local API services

Examples of what you can ask

• “How do I create a transaction in Midaz?”
• “Show me the Go code to onboard an organization.”
• What's the difference between onboarding and transaction APIs?”
• “Help me troubleshoot this 400 error.”
• “List all Midaz account types.”

It’s like talking to a teammate who always has the answer and the right example ready to go.

Available tools and prompts

Lerian MCP provides your assistant with a comprehensive toolbox for exploring documentation, interacting with APIs, and learning through hands-on guidance. Everything runs locally, securely, and in a context-aware manner.

Full documentation access (midaz-docs)

Available operations

• getting-started: Intro to Midaz
• api-reference: Detailed API documentation
• search-endpoints: Search by endpoint or function
• best-practices: Security, performance, and modeling best practices
• architecture: System architecture overview
• sdk-docs: Official SDK documentation
• code-examples: Code example generation
• workflows: Common workflow patterns
• troubleshooting: Issue resolution and diagnostic guides
• search: General documentation search
• sitemap: Full documentation structure
• read: Direct access to a specific page
• browse: Guided browsing through docs

Guided learning tools (midaz-learn)

Available content types

• path: Personalized learning paths
• tutorial: Step-by-step walkthroughs
• concept: In-depth concept explanations
• search: Quick search through learning materials

Domain operations

Organizations

• list-organizations: List all organizations
• get-organization: Get details of a specific organization

Ledgers

• list-ledgers: List all ledgers in an organization
• get-ledger: Get details of a specific ledger

Accounts

• list-accounts: List all accounts under a ledger
• get-account: Get account details
• get-balance: Check account balance

Transactions

• list-transactions: List all transactions
• get-transaction: Get details of a transaction

SDK

• generate-sdk-code: Generate code using official SDKs
• compare-sdk-features: Compare features across SDKs
• find-sdk-examples: Search for specific code examples

Available Prompts

Your assistant also understands a wide range of built-in prompts that adapt content to the user’s experience level, time available, or role.

Documentation

• Format: detailed, summary, examples-only
• Categories: api, guides, examples, models, components

Learning

• Experience level: beginner, intermediate, advanced
• Learning mode: explain, show-me, guide-me, deep-dive
• Time available: 5min, 15min, 30min, 1hour, deep-dive

SDK

• Languages: golang, typescript
• Use cases: basic-setup, organization-crud, transaction-processing, authentication-setup, error-handling

Complexity

• overview: High-level summary
• detailed: Full walkthrough
• deep-dive: Technical deep dive with context

User Roles

• developer: For those writing code
• admin: For system administrators
• business: For data consumers and analysts
• explorer: For users exploring Midaz functionality

Combining tools and prompts

You can combine any tool with a prompt to create a fully personalized experience. For example:

• A beginner developer might use midaz-learn with a tutorial prompt.
• A technical user might access midaz-docs with api-reference for detailed endpoint review.

These combinations unlock dynamic, guided, and highly productive sessions, powered by your assistant.

How does it work?

Lerian MCP teaches your assistant using three key inputs:

1. Documentation

Anything added to llms.txt is immediately available to your LLM, including product guides, examples, and concepts.

2. API tools

The assistant learns how to call your APIs, including endpoints, required fields, and response formats, through structured tools.

3. Prompts and workflows

It learns how to interact: what to ask, when to ask, and how to validate the next step. The result? A smarter, safer, and more proactive AI.

Tool invocation flow

This is the core flow used in most assistant interactions. When you ask your assistant to “create an organization” or “get ledger details,” it follows this sequence:

• LLM calls the tool
• MCP validates and enriches input
• Tool handler is triggered
• API request is sent
• Response is returned to the assistant in real time

The following diagram shows how a tool invocation request flows through the MCP server.

sequenceDiagram
    participant C as MCP Client
    participant S as McpServer
    participant CI as ClientIntegrationManager
    participant TH as ToolHandler
    participant V as Validator
    participant AL as AuditLogger
    
    C->>S: tools/call request (tool_name, arguments)
    S->>CI: adaptRequest(request)
    CI->>CI: analyze client capabilities
    CI->>CI: modify parameters if needed
    CI-->>S: adapted request
    
    S->>TH: invokeool(tool_name, args)
    TH->>AL: logToolInvocation(tool_name, args)
    AL->>AL: write audit log entry
    
    TH->>V: validateArgs(args, schema)
    V->>V: check parameter types
    V->>V: validate business rules
    V->>V: detect injection patterns
    
    alt Validation successful
        V-->>TH: args validated
        TH->>TH: execute tool logic
        TH-->>S: tool result
        S->>CI: adaptResponse(result)
        CI->>CI: format for client
        CI-->>S: adapted response
        S-->>C: tool response
    else Validation failed
        V-->>TH: validation error
        TH->>AL: logError(validation_error)
        TH-->>S: error response (-32602 Invalid Params)
        S-->>C: JSON-RPC error
    end
    
    Note over C,AL: Complete tool execution with security

Tool discovery and registration

Every time the MCP server starts, it registers a set of tools, like get-api-reference, generate-code-examples, and get-architecture-overview. These tools are automatically adapted to the capabilities of each MCP client (e.g., Claude Desktop, Cursor, ChatGPT).

This makes it easy to keep things up to date: once a tool is registered, your assistant knows how to use it.

The following diagram shows how Lerian MCP announces tools to your assistant and makes them usable within the client.

sequenceDiagram
    participant C as MCP Client
    participant S as McpServer
    participant TR as ToolRegistry
    participant FT as FinancialTools
    participant UT as UnifiedTools
    
    C->>S: tools/list request
    S->>TR: getAvailableTools()
    
    TR->>FT: registerFinancialTools()
    FT->>FT: register organization tools
    FT->>FT: register ledger tools  
    FT->>FT: register account tools
    FT->>FT: register transaction tools
    FT->>FT: register balance tools
    FT->>FT: register asset tools
    FT->>FT: register portfolio tools
    FT->>FT: register segment tools
    FT->>FT: register SDK tools
    FT-->>TR: 18 financial tools registered
    
    TR->>UT: registerUnifiedTools()
    UT->>UT: register docs-unified (13 operations)
    UT->>UT: register learn-unified (4 operations) 
    UT-->>TR: 2 unified tools registered
    
    TR-->>S: 21 tools available
    S-->>C: tools list (21 tools)
    
    Note over C,UT: Complete tool registry exposed

Protocol-Level Error Handling

If something goes wrong (e.g., a malformed tool call, an unexpected backend response, or a missing configuration), the MCP server gracefully returns a standardized error. In many cases, the assistant can recover and retry with improved input or fallback logic.

The following diagram shows how Lerian MCP detects, handles, and communicates protocol-level errors.

sequenceDiagram
    participant C as MCP Client
    participant S as McpServer
    participant EH as ErrorHandler
    participant AL as AuditLogger
    
    C->>S: malformed JSON-RPC request
    S->>EH: handleProtocolError()
    
    EH->>EH: identify error type
    EH->>AL: logProtocolError()
    
    alt Parse Error
        EH-->>S: error code -32700
        S-->>C: {"error": {"code": -32700, "message": "Parse error"}}
    else Invalid Request
        EH-->>S: error code -32600
        S-->>C: {"error": {"code": -32600, "message": "Invalid Request"}}
    else Method Not Found
        EH-->>S: error code -32601
        S-->>C: {"error": {"code": -32601, "message": "Method not found"}}
    else Invalid Params
        EH-->>S: error code -32602
        S-->>C: {"error": {"code": -32602, "message": "Invalid params"}}
    else Internal Error
        EH-->>S: error code -32603
        S-->>C: {"error": {"code": -32603, "message": "Internal error"}}
    end
    
    Note over C,AL: JSON-RPC 2.0 compliant error handling

From resources to tools

We've transitioned from static resources to interactive tools, so your assistant can explore, generate, test, and troubleshoot with real interactivity.

What the tools unlock

Lerian MCP tools are designed to help your assistant help you. Here's what they cover:

• API reference: Get detailed endpoint docs with payloads, methods, and examples
• Tutorials and guides: Learn setup, onboarding, and best practices
• Architecture: Explore how components connect, including optional diagrams
• SDK docs: Access Go and TypeScript SDK documentation, with code examples
• Code generation: Generate working snippets for tasks like account creation or fund transfers
• Workflow patterns: Understand common flows like onboarding, reporting, and asset tracking
• Troubleshooting: Get real-time help resolving integration issues
• Search and navigation: Quickly locate relevant topics with advanced filters
• Exploration tools: Run health checks, try guided tours, and explore capabilities

👍

Tip

Want the full reference with all tools and supported parameters? Check the full list on GitHub.

Getting started

Lerian MCP works locally and integrates with multiple AI assistants. All you need is Node.js installed and one of the supported tools below.

Before setting it up, check which tools are available for your operating system:

👍

Tip

For Linux users, we recommend using Claude Code, Cursor, Windsurf, or Continue for the best experience.

Now, pick your assistant and follow the instructions below to connect Lerian MCP.

ChatGPT Desktop

1. Open your MCP config file:

• ~/Library/Application Support/ChatGPT/mcp.json (macOS)
• %APPDATA%\ChatGPT\mcp.json (Windows)

2. Add the following code:

{
  "mcpServers": {
    "lerian": {
      "command": "npx",
      "args": ["@lerianstudio/lerian-mcp-server@latest"]
    }
  }
}

3. Restart the app.

Claude Desktop

1. Open the claude_desktop_config.json file:

• ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
• %APPDATA%\Claude\claude_desktop_config.json (Windows)

2. Add the following code:

{
  "mcpServers": {
    "lerian": {
      "command": "npx",
      "args": ["@lerianstudio/lerian-mcp-server@latest"]
    }
  }
}

3. Restart the app.

Backward Compatibility

The old package name (@lerianstudio/midaz-mcp-server@latest) still works, but is deprecated. Please migrate to @lerianstudio/lerian-mcp-server.

{
  "mcpServers": {
    "midaz": {
      "command": "npx",
      "args": ["@lerianstudio/midaz-mcp-server@latest"]
    }
  }
}

Claude Code

If you are using Claude Code via command line, use the following commands:

• For a one-time setup, use:

npx —yes @lerianstudio/lerian-mcp-server

• To add to the Claude Code, use:

claude mcp add —user lerian “npx —yes @lerianstudio/lerian-mcp-server”

Migration from the old package

If you enabled the MCP, using the old package @lerianstudio/midaz-mcp-server, follow these steps:

1. Remove old package:

npm uninstall -g @lerianstudio/midaz-mcp-server

2. Install new package:

npm install -g @lerianstudio/lerian-mcp-server

3. Update Claude Code

claude mcp remove midaz\
claude mcp add lerian "lerian-mcp-server"

Cursor IDE

1. Go to File > Preferences > Cursor Settings > MCP.
2. Click the +Add new global MCP Server button.
3. Add the following code:

{
  "mcp.servers": {
    "lerian": {
      "command": "npm",
      "args": ["exec", "@lerianstudio/lerian-mcp-server@latest"]
    }
  }
}

4. Restart the app.

Windsurf IDE

1. Go to File> Preferences > Windsurf Settings
2. Click the Manage plugins button in the Cascade section.
3. Click View raw config
4. Add the following code:

{
  "mcpServers": {
    "lerian": {
      "command": "npm",
      "args": ["exec", "@lerianstudio/lerian-mcp-server@latest"]
    }
  }
}

5. Save the file
6. Click Refresh in the Manage plugins tab.

🚧

Attention

On Windsurf IDE, you must use the Cascade panel to ask about Midaz.

Continue (VS Code)

On VS Code, install the Continue extension and add the Lerian MCP code to the config.yamlfile.

You can find the file in the following locations:

• ~/.continue/config.yaml (MacOS / Linux)
• %USERPROFILE%.continue\config.yaml (Windows)

You can also open the file via VS Code:

1. On VS Code, open the Continue panel from the activity bar (or press cmd/ctrl + L).
2. Click the Assistant selector above the main chat input.
3. From that dropdown, select the cog icon next to the "Local Assistant" option
4. It will open the local config.yaml.
5. Add the following code and save the file:

mcpServers:
  - name: Lerian
    command: npx
    args:
      - '@lerianstudio/lerian-mcp-server@latest'

4. Close and reopen VS Code.
5. Open the Continue panel from the Activity bar.

Need help?

Something’s not working?

Let’s get the basics out of the way first:

1. Restart your AI assistant after saving the configuration.
2. Double-check the file path: are you editing the right config file?
3. Run a quick test: Ask your assistant, “Can you access Lerian documentation?”

Still stuck?

• Using Claude Desktop? - Make sure MCP is enabled in your version.
• Using any other AI app? - Confirm that Node.js is installed on your machine.
• Need a hand? - Open a ticket on GitHub Issues .

Migrating from Midaz MCP?

No worries, both packages work exactly the same:

• You can use either @lerianstudio/midaz-mcp-server or @lerianstudio/lerian-mcp-server
• Both MIDAZ_* and LERIAN_* environment variables are supported
• Config files work from either .midaz/ or .lerian/ folders
• CLI commands midaz-mcp-server and lerian-mcp-server are interchangeable

How to switch:

1. Point your config to @lerianstudio/lerian-mcp-server
2. Restart your AI assistant
3. (Optional) Update your env vars from MIDAZ_* to LERIAN_*
4. (Optional) Move your config files to .lerian/

Ready to go?

Your assistant is. Just plug in the config, restart your app, and start building, learning, and shipping faster.