> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quanux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect AI agents via the QuanuX MCP server

> QuanuX runs an MCP server acting as a Tool Authority for AI agents, giving them access to skills, scripts, and trading context via standard MCP tool calls.

QuanuX includes a built-in **Model Context Protocol (MCP) server** that acts as the Tool Authority for any connected AI agent. Instead of each AI client implementing its own understanding of your codebase, strategies, or trading workflows, agents connect to the QuanuX MCP server and discover what they can do through a standardized protocol. The server exposes Agent Skills — structured instruction sets that teach an AI exactly how to perform a specific task within QuanuX — and provides tool calls to list, load, and execute them.

## Start the MCP server

```bash theme={null}
python3 -m server.mcp.server
```

The server starts and listens for MCP client connections. Keep it running alongside your QuanuX core server during any AI-assisted session.

## Configure your AI client

To connect an AI client (Claude Desktop, Cursor, or any MCP-compatible agent) to the QuanuX MCP server, add the following entry to your client's configuration file.

For Claude Desktop, edit `claude_desktop_config.json`. For Cursor, edit your MCP settings file. The structure is the same for both:

```json theme={null}
{
  "mcpServers": {
    "quanux": {
      "command": "python3",
      "args": ["-m", "server.mcp.server"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/QuanuX"
      }
    }
  }
}
```

Replace `/absolute/path/to/QuanuX` with the actual path to your QuanuX installation directory.

<Note>
  The `PYTHONPATH` variable is required so that Python can resolve the `server` module. If you installed QuanuX into a virtual environment, you may also need to point `command` to the Python binary inside that environment — for example, `"/path/to/QuanuX/.venv/bin/python3"`.
</Note>

## MCP tool calls

Once connected, your AI agent has access to three core tool calls that implement a **progressive disclosure** workflow: the agent discovers skills first, then loads only the ones relevant to the current task, then executes scripts as needed. This keeps context usage low while giving the agent full capability on demand.

<AccordionGroup>
  <Accordion title="agent.skills.list — discover available skills">
    Returns a lightweight XML summary of all skills registered with the QuanuX MCP server. Your AI client injects this list into the agent's system prompt so the agent knows which skills exist before it needs to use any of them.

    The agent calls this automatically at session start. You don't invoke it manually — it runs as part of context initialization.
  </Accordion>

  <Accordion title="agent.skills.read(skill_name) — load a skill">
    Fetches the full `SKILL.md` content for a specific skill. When the agent determines that your request matches a skill — for example, you ask it to generate a React component and it recognizes the `react-frontend-standards` skill — it calls this tool to load the complete instructions before it begins generating code.

    Example: if you ask the agent to build a new order entry panel, it will call:

    ```
    agent.skills.read("react-frontend-standards")
    ```

    and receive the full architectural rules, Shadcn usage guidelines, and Backend-Driven UI protocols before writing a single line of code.
  </Accordion>

  <Accordion title="agent.skills.run_script(...) — execute a skill script">
    Some skills include scripts in their `scripts/` directory for tasks that are too complex or stateful to describe in natural language alone — data migrations, build steps, code generation pipelines. This tool call instructs the QuanuX server to execute the specified script in the skill's directory and return the output to the agent.

    The agent uses this when a skill's instructions call for it. You don't need to invoke it directly.
  </Accordion>
</AccordionGroup>

## Figma + QuanuX dual-MCP workflow

The most powerful use of the QuanuX MCP server is in combination with the **Figma Desktop MCP server**. By connecting your AI client to both servers at the same time, you give the agent access to your visual designs (via Figma) and your architectural rules (via QuanuX) simultaneously.

The agent can then take a frame you've selected in Figma, read its layout, components, and design tokens, and generate a production-ready, QuanuX-compliant React component — without you writing a single line of code.

### How the two servers divide responsibility

| Server            | What it provides                                                                               |
| ----------------- | ---------------------------------------------------------------------------------------------- |
| Figma Desktop MCP | Raw design data: layout, spacing, colors, component props, layer names                         |
| QuanuX MCP        | Coding rules: `react-frontend-standards` skill, Shadcn conventions, Backend-Driven UI protocol |

### Configure both servers

Add both entries to your AI client's MCP configuration file:

```json theme={null}
{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "@figma/mcp-server"]
    },
    "quanux": {
      "command": "python3",
      "args": ["-m", "server.mcp.server"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/QuanuX"
      }
    }
  }
}
```

### Run the workflow

<Steps>
  <Step title="Enable Figma Dev Mode">
    Open Figma Desktop. Press **Shift + D** to enter Dev Mode, then open the **Inspect** panel. Enable the MCP Server option if your plan supports it. The default local URL is `http://127.0.0.1:3845/mcp`.
  </Step>

  <Step title="Design your component in Figma">
    Build or open the UI frame you want to implement. Use Auto Layout and name your layers clearly — the agent uses layer names to generate meaningful component and prop names.
  </Step>

  <Step title="Select the frame and prompt the agent">
    Select the frame or component in Figma, then send this prompt to your connected agent:

    > "Inspect the selected Figma node. Generate a React component using the `react-frontend-standards` skill."

    The agent will call `figma.get_selection()` to read the design, then call `agent.skills.read("react-frontend-standards")` to load the QuanuX coding rules, and finally output a `.tsx` file that uses Tailwind for styling, Shadcn components where appropriate, and contains no mock data or hardcoded API calls.
  </Step>

  <Step title="Import the component into QuanuX">
    Place the generated `.tsx` file in the appropriate directory under `client/`. The agent can also help you wire up the data hooks — prompt it to replace any placeholder data calls with the correct QuanuX backend methods.
  </Step>
</Steps>

<Warning>
  The Figma MCP server requires the **Figma Desktop app** with Dev Mode enabled. It does not work with the browser-based Figma editor. If you see a connection refused error, confirm that Figma Desktop is open and that Dev Mode is active in the Inspect panel.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="&#x22;Skill not found&#x22; error">
    The QuanuX MCP server reads skills from `server/skills/` (and `client/skills/` for frontend skills). Verify that the skill directory and its `SKILL.md` file exist. For example, the `react-frontend-standards` skill should be at `client/skills/react-frontend-standards/SKILL.md`.
  </Accordion>

  <Accordion title="Agent does not see QuanuX tools">
    Confirm the MCP server is running (`python3 -m server.mcp.server`) and that `PYTHONPATH` in your client config points to the correct QuanuX root directory. Restart your AI client after changing the configuration — most clients only read MCP settings on startup.
  </Accordion>

  <Accordion title="Multiple MCP servers not supported">
    The dual-server Figma workflow requires an AI client that supports connecting to more than one MCP server simultaneously. Claude Desktop and Cursor both support this. If your client only allows one server, you will not be able to use the Figma + QuanuX workflow without a custom bridge.
  </Accordion>
</AccordionGroup>