Lyrra Studio MCP server

Model Context Protocol (MCP) server for Lyrra Studio: your assistant (Claude Desktop, Cursor, n8n MCP Client, …) connects via MCP. This process exposes one MCP tool per backend OpenAPI operation, plus lyrra_meta, lyrra_search_operations, and lyrra://… resources.

MCP vs “calling the API”

| What | Role | |------|------| | MCP | How the AI client talks to this package (stdio or Streamable HTTP /mcp). | | LYRRA_API_URL | Where this MCP server reaches your Lyrra Studio app over HTTP (…/api). It is not a separate integration mode: every MCP tool call is translated into REST requests to that base. |

If you integrate without MCP (scripts, Postman, custom backend), call Lyrra’s REST API directly. If you use this npm package, you use MCP; the env var only points the server at your Lyrra instance.

Prerequisites

• Node.js ≥ 20
• A running Lyrra Studio backend with openapi/openapi.json generated (npm run openapi:generate in apps/backend of the monorepo)

Install from npm (Claude / Cursor)

Published as @lyrra/mcp-server. No local clone required:

npx -y @lyrra/mcp-server lyrra-mcp

(Paquet avec plusieurs binaires : lyrra-mcp, lyrra-mcp-http, mcp-server — sans nom explicite, npx peut répondre could not determine executable to run.)

In Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "lyrra-studio": {
      "command": "npx",
      "args": ["-y", "@lyrra/mcp-server", "lyrra-mcp"],
      "env": {
        "LYRRA_API_URL": "https://your-domain.com/api",
        "LYRRA_CLIENT_ID": "rak_xxxxxxxx",
        "LYRRA_CLIENT_SECRET": "rak_xxxxxxxx_yyyyyyyy_zzzzzzzzzzzzzzzz"
      }
    }
  }
}

LYRRA_API_URL must be your Lyrra REST base (usually https://<host>/api) so MCP tools can execute against the right environment. Do not use the Streamable HTTP MCP URL here (not …/mcp/api) — that is only for clients that speak MCP over HTTPS to path /mcp, not for LYRRA_API_URL.

Use Header Auth keys from the institution dashboard instead of client id/secret:

"env": {
  "LYRRA_API_URL": "https://your-domain.com/api",
  "LYRRA_MCP_HEADER_NAME": "X-Lyrra-Api-Key",
  "LYRRA_MCP_HEADER_VALUE": "rak_…full secret…"
}

Global install (optional): npm install -g @lyrra/mcp-server then run lyrra-mcp or mcp-server (binaries on PATH).

Troubleshooting (logs Claude / Cursor)

| Symptôme | Cause fréquente | Correctif | |----------|-----------------|-----------| | Cannot find module '/dist/index.js' | command = node et args = dist/index.js sans répertoire de travail du paquet | Utiliser npx + args ci-dessus, ou node avec chemin absolu vers …/node_modules/@lyrra/mcp-server/dist/index.js | | node: bad option: -y | command = node au lieu de npx | command doit être npx, pas node | | could not determine executable to run | Plusieurs bin dans le paquet npm | Ajouter lyrra-mcp en dernier argument : ["-y", "@lyrra/mcp-server", "lyrra-mcp"] | | Réponses API en HTML (Unexpected token '<') | LYRRA_API_URL pointe vers le frontend ou une URL sans /api | Mettre https://<hôte>/api (base REST réelle) | | OpenAPI introuvable …/mcp/api/openapi.json | LYRRA_API_URL = …/mcp/api (confusion avec l’URL MCP HTTP) | Utiliser …/api uniquement ; optionnel : LYRRA_OPENAPI_URL=https://<hôte>/api/openapi.json | | @lyrra/mcp-server 404 sur npm | Scope / publication | Vérifier que le paquet est bien public sur npm sous @lyrra/mcp-server |

Streamable HTTP / n8n (MCP URL https://…/mcp)

Some clients need an HTTPS MCP endpoint (not stdio). They use Streamable HTTP on path /mcp — still MCP, not “the REST API” as the client protocol.

• Docker: service mcp-http in docker-compose.yml and Nginx location /mcp (see apps/frontend/nginx.default.conf in the monorepo).
• Auth: n8n Header Auth — same header name and full secret as an institution Header auth key (e.g. X-Lyrra-Api-Key + rak_…).
• Run locally: LYRRA_API_URL=http://localhost:3001/api npm run start:http → listens on LYRRA_MCP_HTTP_PORT (default 3457), MCP path /mcp.
• n8n « Could not connect » : the MCP SDK requires Accept to include both application/json and text/event-stream on POST. lyrra-mcp-http patches missing values so n8n can connect; ensure mcp-http + Nginx /mcp are deployed, and Header Auth Value is the full rak_… secret (same as at key creation).

Binaries after global install: lyrra-mcp (stdio MCP) and lyrra-mcp-http (HTTP MCP).

Develop from this monorepo

cd lyrra-studio-app/apps/mcp-server
npm ci
npm run build

Publish a new version (maintainers)

1. Create an npm organization or user scope @lyrra and log in: npm login.
2. Bump version in package.json (semver).
3. From apps/mcp-server: npm publish
   (publishConfig.access is public for the scoped package.)

Ensure dist/ is built (prepublishOnly runs npm run build automatically).

Publish error: Cannot implicitly apply the "latest" tag because previously published version … is higher — the registry already has a newer semver on latest (e.g. 1.1.3). Bump package.json to something greater (e.g. 1.1.4), not 1.0.x. Alternatively: npm publish --tag maintenance to publish an older line without moving latest.

Run npm pkg fix in this folder to apply npm’s suggested package.json fixes (bin, repository, …).

Environment variables

| Variable | Purpose | |----------|---------| | LYRRA_API_URL | Lyrra Studio REST base the MCP server uses internally to run tools (e.g. https://yourdomain/api). Required for MCP to reach your app — not a choice between “API or MCP”. | | LYRRA_CLIENT_ID | Key prefix (keyPrefix) for client_credentials keys | | LYRRA_CLIENT_SECRET | Full secret rak_… | | LYRRA_ACCESS_TOKEN | (optional) Bearer JWT if not using key exchange | | LYRRA_MCP_HEADER_NAME | (optional) HTTP header for Header Auth keys (e.g. X-Lyrra-Api-Key; alias LYRRA_HEADER_AUTH_NAME) | | LYRRA_MCP_HEADER_VALUE | (optional) Same secret as shown once at key creation (aliases LYRRA_MCP_HEADER_SECRET, LYRRA_HEADER_AUTH_VALUE) | | LYRRA_OPENAPI_URL | (optional) Full OpenAPI JSON URL if not {origin}/api/openapi.json | | LYRRA_MCP_MAX_TOOLS | (optional) Cap registered tools (integer) | | LYRRA_MCP_HTTP_PORT | (HTTP MCP only) Listen port (default 3457) | | LYRRA_MCP_SKIP_AUTH_VALIDATE | (optional) 1 = skip GET /api/auth/me on each HTTP MCP request (insecure; dev only) | | LYRRA_MCP_EXTRA_INBOUND_HEADERS | (HTTP MCP) Extra incoming header names to forward to Lyrra when calling REST |

Client ID + Secret → POST /api/auth/api-key/token for a JWT. Header Auth keys skip that: the MCP server sends the header on each REST call it makes to Lyrra (same idea as n8n Header Auth).

EduFlow block documentation (MCP tools)

• lyrra_eduflow_blocks_index: documented block types.
• lyrra_eduflow_block_<type> (e.g. lyrra_eduflow_block_quiz_mcq): per-type sheet — role, data / settings, graph, persistence.
• Source: src/eduflow-block-docs.ts in the monorepo.

Run (local / monorepo)

npm start

Development (no pre-build): npm run dev

Automated test (no Lyrra backend)

A minimal OpenAPI is served locally; the script checks MCP initialize, tools/list, and a tools/call on a block sheet:

npm run test:mcp

MCP client wiring (npm vs monorepo)

• Recommended: command npx, args ["-y", "@lyrra/mcp-server"] (see above).
• Local monorepo: command node, args: absolute path to apps/mcp-server/dist/index.js after npm run build.
  Same env as npm (LYRRA_API_URL, credentials or header variables).