# MADA

*Setup Reference Card*

LLNL’s Multi-Agent Design Assistant • GitHub: <https://github.com/llnl/mada> \| <https://github.com/llnl/mada-tools> • Documentation: <https://software.llnl.gov/mada/develop/> \| <https://software.llnl.gov/mada-tools/develop/>

**MADA** is a multi-agent design assistant platform that helps users build custom AI agents and orchestrate them using Microsoft Agent Framework. The broader MADA ecosystem also includes **MADA Tools**, a Python-based repository that provides reusable AI tooling for those agents, including MCP servers, skills files, and other resources that support agent workflows. Together, MADA and MADA Tools provide both the framework for creating agents and the tools they use to get work done.

## 1 · Install

<table>
<colgroup>
<col style="width: 100%" />
</colgroup>
<thead>
<tr>
<th><p><strong>Tip:</strong> More information on installation instructions can be found in the documentation for each project:</p>
<ul>
<li><p><a href="https://software.llnl.gov/mada/develop/user_guide/installation/">MADA Installation</a></p></li>
<li><p><a href="https://software.llnl.gov/mada-tools/develop/user_guide/installation/">MADA Tools Installation</a></p></li>
</ul></th>
</tr>
</thead>
<tbody>
</tbody>
</table>

Installation of MADA requires Python \>= 3.11 to be running on your machine.

<table>
<colgroup>
<col style="width: 100%" />
</colgroup>
<thead>
<tr>
<th><p>python -m venv venv # create virtual environment</p>
<p>source venv/bin/activate # activate virtual environment</p>
<p>pip install mada # install mada</p>
<p>pip install mada-tools # install mada-tools</p></th>
</tr>
</thead>
<tbody>
</tbody>
</table>

**Verify the install** — open a new terminal in your project, then:

<table>
<colgroup>
<col style="width: 100%" />
</colgroup>
<thead>
<tr>
<th><p>mada --help # help menu</p>
<p>mada-tools --help # help menu</p>
<p>mada-tools --version # version</p>
<p>mada-tools available-servers # display available MCP Servers</p></th>
</tr>
</thead>
<tbody>
</tbody>
</table>

## 2 · Connect a Model Provider — Model Access Gateway (MAG)

MADA needs a provider that serves LLM models.

### Step 1 — Create a personal access token

Use the links below to create your keys and save them somewhere safe

- MAG <https://amsc-docs-d762d2.gitlab.io/model-access-gateway/#quick-start>

  - *Instructions to get an AmSC account, request access to a project, and generate PAT (Personal Access Token) to access MAG are listed above.*

### Step 2 — Set environment variables

Export your environment variables so they can be seen by MADA.

<table>
<colgroup>
<col style="width: 100%" />
</colgroup>
<thead>
<tr>
<th><p># MAG</p>
<p>export AMSC_I2_API_KEY=&lt;key&gt;</p>
<p>export OPENAI_BASE_URL=“https://i2-api.genesis.american-science-cloud.org/”</p></th>
</tr>
</thead>
<tbody>
</tbody>
</table>

### Step 3 — Edit Configuration

Edit the \`mada/configs/example_helpful_critic.json\` configuration file from the [MADA repository](https://github.com/llnl/mada/) to use exported environment variables.

<table>
<colgroup>
<col style="width: 100%" />
</colgroup>
<thead>
<tr>
<th><p># MAG</p>
<p>{</p>
<p>"model": {</p>
<p>"provider": "openai",</p>
<p>"model": "gpt-5.6",</p>
<p>"api_key": "${AMSC_I2_API_KEY}",</p>
<p>"base_url": "${OPENAI_BASE_URL}"</p>
<p>},</p>
<p>…</p></th>
</tr>
</thead>
<tbody>
</tbody>
</table>

### Step 4 — Connect

Ensure the connections are working by running the following commands.

<table>
<colgroup>
<col style="width: 100%" />
</colgroup>
<thead>
<tr>
<th><p>mada-cli mada/configs/example_helpful_critic.json # Use configuration file to start mada</p>
<p># you should now see the output below</p>
<p>MADA Multi-Agent Orchestrator</p>
<p>==================================================</p>
<p>Chat Session Manager</p>
<p>==================================================</p>
<p>Existing sessions:</p>
<p>1. 2026-05-26 07:07:54 | a7da842f-a44b-402a-b640-a1ae76d31f02</p>
<p>Options:</p>
<p>[n] New session</p>
<p>[s] Select session</p>
<p>[d] Delete session</p>
<p>[a] Delete ALL sessions</p>
<p>[q] Quit</p>
<p>Enter choice: n</p>
<p>Created and selected a new session.</p>
<p>Initializing agents and MCP servers...</p>
<p>Status: Connection Successful: Orchestrator initialized with 0 MCP Servers and 3 agents</p>
<p>Model: gpt-5.4 from livai</p>
<p>No MCP tools available (LLM-only agents)</p>
<p>Chat with the agents (type 'quit' to exit)</p>
<p>--------------------------------------------------</p>
<p>You: Hi</p>
<p>Agents:</p>
<p>--------------------</p>
<p>Hi! How can I help?</p></th>
</tr>
</thead>
<tbody>
</tbody>
</table>

## 3 · Per-Project Settings

<table>
<colgroup>
<col style="width: 100%" />
</colgroup>
<thead>
<tr>
<th><p><strong>Tip:</strong> More documentation on configuring MADA and MADA Tools can be found in their respective sets of documentation:</p>
<ul>
<li><p><a href="https://software.llnl.gov/mada/develop/user_guide/configuration/">MADA Configuration</a></p></li>
<li><p><a href="https://software.llnl.gov/mada-tools/develop/user_guide/configuration/">MADA Tools Configuration</a></p></li>
</ul></th>
</tr>
</thead>
<tbody>
</tbody>
</table>

We used the [Example/Helpful Critic configuration](https://github.com/llnl/mada/blob/develop/configs/example_helpful_critic.json) above that only has LLM agents without any tools. These configurations can be changed to include MCP tools by filling in the \`“mcp_servers”\` key with a list of available MCP servers. See the [MADA Vertex CFD configuration](https://github.com/llnl/mada/blob/develop/configs/orchestrator_vertex_cfd.json) for an example.

These MCP Servers are defined in the mada-tools repo and have a corresponding configuration file. We use this configuration to start the MCP Servers so the LLM can have access to their tools. See the [MADA Tools Vertex CFD configuration](https://github.com/llnl/mada-tools/blob/develop/configs/vertex_cfd_servers.json) for an example. The mada-tools repo is designed to create and integrate modular MCP Servers as the user sees fit.

| **IMPORTANT:** The ports in both configuration files must match in order for the connection to be successful |
|----|

<table>
<colgroup>
<col style="width: 100%" />
</colgroup>
<thead>
<tr>
<th><p>mada-tools start-servers mada-tools/configs/vertex_cfd_servers.json # start mcp servers with mada-tools</p>
<p>mada-cli mada/configs/orchestrator_vertex_cfd.json # Use mada to start llm agent interaction</p>
<p># you should now see the output below</p>
<p>MADA Multi-Agent Orchestrator</p>
<p>==================================================</p>
<p>Chat Session Manager</p>
<p>==================================================</p>
<p>Existing sessions:</p>
<p>1. 2026-07-07 12:16:21 | 02fff2a1-33a2-4e43-b9b4-0b558a581cb2</p>
<p>Options:</p>
<p>[n] New session</p>
<p>[s] Select session</p>
<p>[d] Delete session</p>
<p>[a] Delete ALL sessions</p>
<p>[q] Quit</p>
<p>Enter choice: n</p>
<p>Created and selected a new session.</p>
<p>Initializing agents and MCP servers...</p>
<p>Status: Connection Successful: Orchestrator initialized with <strong>2 MCP Servers</strong> and 3 agents</p>
<p>Model: gpt-5.4 from livai</p>
<p><strong>Available tools:</strong></p>
<p><strong>• JobManagementAgent: flux</strong></p>
<p><strong>• SimulationAgent: vertex_cfd</strong></p>
<p>Chat with the agents (type 'quit' to exit)</p>
<p>--------------------------------------------------</p>
<p>You: What tools are available</p>
<p>Agents:</p>
<p>--------------------</p>
<p>Available tools:</p>
<p>- JobManagementAgent — executes computational workflows</p>
<p>- SimulationAgent — creates simulation parameter runs and analyzes results</p>
<p>There is also:</p>
<p>- multi_tool_use.parallel — lets me call multiple specialist tools in parallel when appropriate</p>
<p>If you want, I can also explain when I’d use each one.</p></th>
</tr>
</thead>
<tbody>
</tbody>
</table>

## 4 · Everyday Commands

<table>
<colgroup>
<col style="width: 100%" />
</colgroup>
<thead>
<tr>
<th><p><strong>TIP:</strong> More documentation on using MADA and MADA Tools can be found in their respective sets of documentation:</p>
<ul>
<li><p><a href="https://software.llnl.gov/mada/develop/user_guide/usage/">Using MADA</a></p></li>
<li><p><a href="https://software.llnl.gov/mada-tools/develop/user_guide/cli/">MADA Tools CLI</a> and <a href="https://software.llnl.gov/mada-tools/develop/user_guide/usage/">Using MADA Tools</a></p></li>
</ul></th>
</tr>
</thead>
<tbody>
</tbody>
</table>

| **Command** | **What it does** |
|----|----|
| **mada-tools** |  |
| mada-tools available-servers | View available servers. |
| mada-tools start-servers path/to/mcp_config.json | Start MCP servers. |
| mada-tools stop-servers | Stop running MCP servers. |
| mada-tools servers-status | Check status of MCP servers. |
| mada-tools restart-servers path/to/mcp_config.json | Restart MCP servers. |
|  |  |
| **mada** |  |
| mada-cli path/to/agent_config.json | Start MADA in CLI mode. |
| mada-gradio path/to/agent_config.json | Start MADA in GUI mode. Uses Gradio. |
| mada-openai-api path/to/agent_config.json | Start MADA in OpenAI API mode. |