> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # 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. How a tool invocation flows through the Lerian MCP server, from the assistant's call through input validation and the API request to the returned response ### 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. How the Lerian MCP server registers its tools on startup and announces them to the assistant so they become usable inside 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. How the Lerian MCP server detects a protocol-level error, returns a standardized error, and lets the assistant recover and retry ## 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](https://github.com/LerianStudio/lerian-mcp-server). ## Getting started *** **Lerian MCP** works locally and integrates with multiple AI assistants. All you need is [Node.js](https://nodejs.org/en/download) 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 * `~/Library/Application Support/ChatGPT/mcp.json` (macOS). * `%APPDATA%\ChatGPT\mcp.json` (Windows). ```bash Shell theme={null} { "mcpServers": { "lerian": { "command": "npx", "args": ["@lerianstudio/lerian-mcp-server@latest"] } } } ``` Restart the app. ### Claude Desktop * `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS). * `%APPDATA%\Claude\claude_desktop_config.json` (Windows). ```bash Shell theme={null} { "mcpServers": { "lerian": { "command": "npx", "args": ["@lerianstudio/lerian-mcp-server@latest"] } } } ``` 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`. ```bash Shell theme={null} { "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: ```bash Shell theme={null} npx --yes @lerianstudio/lerian-mcp-server ``` * To add it to Claude Code, use: ```bash Shell theme={null} 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: ```bash Shell theme={null} npm uninstall -g @lerianstudio/midaz-mcp-server ``` ```bash Shell theme={null} npm install -g @lerianstudio/lerian-mcp-server ``` ```bash Shell theme={null} npm install -g @lerianstudio/lerian-mcp-server ``` ```bash Shell theme={null} claude mcp remove midaz\ claude mcp add lerian "lerian-mcp-server" ``` ### Cursor IDE Go to **File** > **Preferences** > **Cursor Settings** > **MCP**. Click the **+Add new global MCP Server** button. Add the following code: ```bash Shell theme={null} { "mcp.servers": { "lerian": { "command": "npm", "args": ["exec", "@lerianstudio/lerian-mcp-server@latest"] } } } ``` Restart the app. ### Windsurf IDE Go to **File**> **Preferences** > **Windsurf Settings**. Click the **Manage plugins** button in the *Cascade* section. Click **View raw config**. Add the following code: ```bash Shell theme={null} { "mcpServers": { "lerian": { "command": "npm", "args": ["exec", "@lerianstudio/lerian-mcp-server@latest"] } } } ``` Save the file. 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.yaml`file. 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: On VS Code, open the **Continue** panel from the activity bar (or press `cmd/ctrl + L`). Click the **Assistant** selector above the main chat input. From that dropdown, select the cog icon next to the "Local Assistant" option. It will open the local `config.yaml`. Add the following code and save the file: ```bash JSON theme={null} mcpServers: - name: Lerian command: npx args: - '@lerianstudio/lerian-mcp-server@latest' ``` Close and reopen VS Code. Open the **Continue** panel from the *Activity bar*. ## Need help? *** #### Something’s not working? Let’s get the basics out of the way first: **Restart your AI assistant** after saving the configuration. Are you editing the right config file? 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](https://github.com/lerianstudio/lerian-mcp-server/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:** Point your config to `@lerianstudio/lerian-mcp-server`. Restart your AI assistant. (Optional) Update your env vars from `MIDAZ_*` to `LERIAN_*`. (Optional) Move your config files to `.lerian/`. ## Ready to go? *** Your assistant is ready. Plug in the config, restart your app, and start building.