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

# MCP System

> Let your AI assistant know and call the LeaderOS API with @leaderos/headless-mcp.

## What is MCP?

The **Model Context Protocol (MCP)** is an open standard that lets AI assistants (Claude Code, Cursor, Windsurf and others) use external tools and data. `@leaderos/headless-mcp` is an MCP server that introduces **your site's** Headless API to your assistant.

Without MCP the assistant guesses the API and may invent endpoints or field names. With MCP it:

* **searches** endpoints and reads their real parameter/response schemas,
* looks at your site's **actual configuration** (which modules are on, which captcha pages exist),
* takes **sample responses** from your live site and builds the UI around them.

## Installation

Requirement: Node.js 18.18+. The package runs through `npx`; you do not install it separately.

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add leaderos \
>   -e LEADEROS_URL=https://your-site.com \
>   -e LEADEROS_PUBLIC_KEY=pk_live_XXXXXXXX \
>   -- npx -y @leaderos/headless-mcp
> ```

> [tab] .mcp.json (Cursor etc.)
>
> Create `.mcp.json` in the project root (`create-leaderos-theme` already adds it):
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "leaderos": {
>       "command": "npx",
>       "args": ["-y", "@leaderos/headless-mcp"],
>       "env": {
>         "LEADEROS_URL": "https://your-site.com",
>         "LEADEROS_PUBLIC_KEY": "pk_live_XXXXXXXX"
>       }
>     }
>   }
> }
> ```

> [!NOTE]
>
> The template's `.mcp.json` reads `${LEADEROS_URL}` and `${LEADEROS_PUBLIC_KEY}` from environment variables. The values are also in `.env.local`; you can write the values directly if needed.

## Environment variables

| Variable | Required | Description |
| - | - | - |
| `LEADEROS_URL` | Yes | Site address, e.g. `https://your-site.com` |
| `LEADEROS_PUBLIC_KEY` | For `call_endpoint` | `pk_live_...` |
| `LEADEROS_TOKEN` | No | A user token for trying endpoints that need a login |
| `LEADEROS_ALLOW_WRITE` | No | `1` allows POST/PUT/PATCH/DELETE calls (default: GET only) |
| `LEADEROS_OPENAPI` | No | Local file path or URL; default `<LEADEROS_URL>/headless/openapi.json` |

> [!WARNING]
>
> Enable `LEADEROS_ALLOW_WRITE=1` **only on a test site**. The AI could create real orders, credit transfers or forum posts.

## Tools

| Tool | What it does |
| - | - |
| `search_endpoints` | Searches endpoints by keyword (path, summary, tag, operationId). Returns method, path, auth type and SDK `operationId` |
| `get_endpoint` | Parameters, request body, response schemas, error codes, captcha page and authentication of one endpoint |
| `get_schema` | Returns a component schema by name (`Cart`, `StoreProduct`, `ForumThread`, `PaymentIntent`…) |
| `call_endpoint` | Sends a real request to the configured site. GET only by default |
| `get_site_config` | `/site/config`: site name, game, active modules, captcha pages, branding rule, currencies |
| `list_error_codes` | Every error code and the endpoints that return it |
| `scaffold_page` | Generates a Next.js page skeleton for a GET endpoint |

It also exposes a **resource**: `leaderos://llms-full.txt` (the full API reference).

## Example

You can ask your assistant:

> "Build a page that lists store products by category. First check which modules are on."

The assistant will typically:

1. `get_site_config` → sees the `store` module is active.
2. `search_endpoints("store products")` → finds the `GET /store/...` endpoints.
3. `get_endpoint` and `get_schema("StoreProduct")` → learns the field names.
4. `call_endpoint` → looks at real product data.
5. `scaffold_page` → takes the skeleton and adapts it to your design.

## Security

* The default mode is **read-only**.
* The MCP server runs only on your machine; your site key is not sent to third parties.
* The public key is not sensitive, but still do not commit it; `.env.local` is in `.gitignore`.

## Troubleshooting

| Symptom | Fix |
| - | - |
| `Set LEADEROS_URL` error | Define the environment variable |
| `Could not load .../openapi.json (HTTP 404)` | Headless API is off in the panel or the URL is wrong |
| `call_endpoint` 401 `INVALID_API_KEY` | The key may have been regenerated; update it |
| Login-only endpoint returns `UNAUTHENTICATED` | Set `LEADEROS_TOKEN` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.