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.
  • No API keys are needed 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.

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

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

​
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.
AspectResourcesDocumentation tools
Client supportLimitedFull support across all MCP clients.
FunctionalityStatic contentContextual, interactive, dynamic.
ExamplesBasic textProduction-ready code.
SearchNoneFuzzy search with filters.
TroubleshootingNot availableDiagnostic tools and prevention tips.
InteractivityRead-onlyGuided tours, demos, and code generation.

​
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.
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:
ToolLinuxmacOSWindowsNotes
ChatGPT Desktop Unofficial Yes YesLinux builds available via Flatpak and AppImage (community maintained).
Claude Desktop No Yes YesNot supported on Linux.
Claude Code (CLI) Yes Yes YesTerminal-based, works anywhere with Node.js.
Cursor IDE Yes Yes YesElectron-based, officially supports all platforms.
Windsurf IDE Yes Yes YesLinux support available, though slightly limited.
Continue (VS Code) Yes Yes YesVS 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

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

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

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.
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'
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.
  • 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.