Lerian MCP

Connect AI assistants like Claude, Cursor, or Windsurf to the Midaz ecosystem with secure, real-time access to docs, APIs, and local services.

Lerian MCP connects your AI assistant directly to the Midaz ecosystem. Whether you use 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 local services.

The assistant reads the docs, generates code, and runs actions for you, so you move faster.

What is MCP?

---

MCP stands for Model Context Protocol. Think of it as Bluetooth for LLMs. It is how your AI learns what tools it can use and how your system works. It also learns what questions to ask to finish the job.

Lerian MCP teaches your assistant to:

• Understand documentation, architecture, and SDKs.
• Use APIs through built-in tools.
• Ask follow-up questions to guide itself.

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

Why use Lerian MCP?

---

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

• Search Midaz documentation with natural language.
• Call local Midaz APIs through 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 build new integrations or support production systems, Lerian MCP gives your LLM the context it needs, safely and instantly.

Built for security

---

Lerian MCP keeps security first. It:

• Runs entirely on your machine.
• Has read-only access by default.
• Requires your explicit approval before it writes data.
• Needs no API keys for local setup.
• Is source available 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.”

Available tools and prompts

---

Lerian MCP gives your assistant a small set of tools to explore documentation, call APIs, and learn through guided steps. Everything runs locally and read-first.

Core tools

• lerian: the read-oriented entry point for documentation, learning, SDK examples, product discovery, and search.
• portfolio-workflow: runs cross-product workflows across Lerian products.

The lerian tool

The lerian tool takes an operation parameter. Each operation covers one need:

• discover: summarize a product and the tools it exposes.
• docs: look up product documentation.
• learn: return guided learning for a topic.
• sdk: return SDK code examples in Go or TypeScript.
• search: search across product knowledge.

Live Midaz API tools

Two tools give your assistant live access to a running Midaz:

• midaz-discover: returns the available resources, actions, parameters, and request schemas. It is read-only.
• midaz-execute: calls the Midaz API with a contract from midaz-discover.

Call midaz-discover before midaz-execute. A write action needs explicit confirmation and an audit reason.

Built-in prompts

Lerian MCP also ships built-in prompts that guide common tasks. For example, a prompt can help you onboard a first organization, learn a concept, or debug an API call. Each prompt adapts to your experience level and role.

How does it work?

---

Lerian MCP teaches your assistant using three key inputs:

1. Documentation

Your LLM can immediately use anything you add to llms.txt, 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.

Tool invocation flow

Most assistant interactions use this core flow. When you ask your assistant to “create an organization” or “get ledger details,” it follows this sequence:

• The LLM calls the tool.
• MCP validates and enriches the input.
• The MCP server triggers the tool handler.
• The tool sends the API request.
• The tool returns the response to the assistant in real time.

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

Tool discovery and registration

Every time the MCP server starts, it registers its tools, such as lerian, midaz-discover, and midaz-execute. The server adapts these tools to the capabilities of each MCP client, such as Claude Desktop, Cursor, or ChatGPT.

This keeps things up to date. After the server registers a tool, 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.

Protocol-Level Error Handling

If something goes wrong, such as a malformed tool call, an unexpected backend response, or a missing configuration, the MCP server returns a standardized error. In many cases, the assistant can recover and retry with better input or fallback logic.

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

From resources to tools

---

Lerian MCP moved from static resources to interactive tools. Your assistant can now explore, generate, test, and troubleshoot directly.

Aspect	Resources	Documentation tools
Client support	Limited	Full support across all MCP clients.
Functionality	Static content	Contextual, interactive, dynamic.
Examples	Basic text	Production-ready code.
Search	None	Fuzzy search with filters.
Troubleshooting	Not available	Diagnostic tools and prevention tips.
Interactivity	Read-only	Guided tours, demos, and code generation.

What the tools unlock

Lerian MCP tools help your assistant help you. 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.

Want the full reference with all tools and parameters? See the lerian-mcp-server README 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 you set it up, check which tools are available for your operating system:

Tool	Linux	macOS	Windows	Notes
ChatGPT Desktop	Unofficial	Yes	Yes	Linux builds available via Flatpak and AppImage (community maintained).
Claude Desktop	No	Yes	Yes	Not supported on Linux.
Claude Code (CLI)	Yes	Yes	Yes	Terminal-based, works anywhere with Node.js.
Cursor IDE	Yes	Yes	Yes	Electron-based, officially supports all platforms.
Windsurf IDE	Yes	Yes	Yes	Linux support available, though slightly limited.
Continue (VS Code)	Yes	Yes	Yes	VS Code extension, fully cross-platform.

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

   Shell

   {
     "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

   Shell

   {
     "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 now deprecated. Migrate to @lerianstudio/lerian-mcp-server.

Shell

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

Claude Code

If you use Claude Code from the command line, use the following commands:

• For a one-time setup, use:

Shell

npx --yes @lerianstudio/lerian-mcp-server

• To add it to Claude Code, use:

Shell

claude mcp add --scope user lerian -- npx --yes @lerianstudio/lerian-mcp-server

Migration from the old package

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

1. Remove old package

   Shell

   npm uninstall -g @lerianstudio/midaz-mcp-server
   
2. Install new package

   Shell

   npm install -g @lerianstudio/lerian-mcp-server
   
3. Update Claude Code

   Shell

   npm install -g @lerianstudio/lerian-mcp-server
   
4. Update Claude Code

   Shell

   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:

   Shell

   {
     "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:

   Shell

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

6. Click Refresh in the Manage plugins tab.

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:

   JSON

   mcpServers:
     - name: Lerian
       command: npx
       args:
         - '@lerianstudio/lerian-mcp-server@latest'
   
6. Close and reopen VS Code.

7. 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.
• Lerian MCP supports both MIDAZ_* and LERIAN_* environment variables.
• 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 ready. Plug in the config, restart your app, and start building.