loreto-mcp

Turn any YouTube video, article, PDF, or image into a reusable Claude Code skill — without leaving your editor.

What it does

Loreto analyzes a content source and extracts structured skill packages that Claude Code can apply to future tasks. Each skill contains:

• `SKILL.md` — Principles, failure modes, implementation steps, and architectural patterns
• `README.md` — Overview and usage context
• Reference files — Supporting patterns and data structures
• Test script — Runnable validation for the skill's core concepts

Save skills to `.claude/skills/` and Claude picks them up automatically on relevant tasks — reducing hallucinations, token usage, and re-explaining the same concepts over and over.

Sample skills

Every skill Loreto generates ships as its own standalone, installable repo. These nine were generated from a single technical video on hybrid AI architecture — clone any of them directly:

Each repo has a human-facing README plus the skill itself in a same-named subfolder — `cp -r / ~/.claude/skills/` and Claude picks it up automatically.

Anatomy of a generated skill

You don't have to clone anything to see what Loreto produces. Every generation

is a ready-to-run package — a `SKILL.md` (principles, failure modes,

implementation steps, Mermaid diagrams), supporting `references/`, and a

runnable `tests/` script. The standalone repos wrap each one with a human

README and the skill in a same-named subfolder:

designing-hybrid-context-layers/          ← public repo
├── README.md                             ← for humans, not part of the skill
└── designing-hybrid-context-layers/      ← the skill (cp into ~/.claude/skills/)
    ├── SKILL.md
    └── references/
        ├── architecture-patterns.md
        └── retrieval-decision-matrix.md

A trimmed look at the `SKILL.md` Loreto generated for that skill:

~~~markdown

name: designing-hybrid-context-layers

description: >

Designs hybrid AI context architectures that combine RAG, knowledge graphs,

episodic memory, and long-context synthesis appropriately. Use when ...

Designing Hybrid Context Layers

The Three-Layer Context Model

Layer 1: Factual Store (Vector RAG)

Layer 2: Relational Store (Knowledge Graph)

Layer 3: Temporal/Episodic Store (Timeline Index)

flowchart TD
    Q[Incoming Query] --> R{Query Router}
    R -->|single fact| L1[Layer 1 — Vector RAG]
    R -->|relationships| L2[Layer 2 — Knowledge Graph]
    R -->|sequence / causation| L3[Layer 3 — Timeline Index]

Anti-Pattern: The RAG-for-Everything Trap

Implementation Roadmap

~~~

Prefer not to leave your editor at all? The free `list_skills` and `get_skill`

MCP tools return the same structured records, and `verify_artifacts` proves any

past generation by `generation_id` — discover, inspect, and verify before you

ever clone.

Billing — two paths, pick one

Loreto runs on two parallel billing paths. The right one depends on whether you're a human signing up or an AI agent paying per task.

Path A — API key (this MCP package)

Get your key at loreto.io, set `LORETO_API_KEY` in your MCP config (see below), and you're done. Free tier ships immediately; upgrade to Pro when you need more.

Path B — x402 pay-per-call (no signup)

If you're an autonomous agent, an AI workflow without persistent credentials, or a developer who just wants to try one generation, x402 is faster than signing up. The MCP package itself uses Path A — but every catalog call (`list_skills`, `get_skill`, `verify_artifacts`, `estimate_cost`) is free regardless of which path you generate skills under.

To run a generation under x402:

# Pseudocode — see https://loreto.io/docs-x402 for the full handshake
curl -X POST https://api.loreto.io/api/v1/skills/x402/generate \
  -H "X-PAYMENT: " \
  -H "Content-Type: application/json" \
  -d '{"source": "https://www.youtube.com/watch?v=...", "source_type": "youtube"}'

The `X-PAYMENT` header is signed by your wallet against an EIP-3009 USDC transfer authorization for $0.75. The Loreto server only burns the authorization on a successful 2xx response — failed pipeline runs don't consume your USDC. Use the x402 Python SDK to handle the signing.

Verify any generation by id. Both paths return a `generation_id` (uuid4). Pass it to the MCP's `verify_artifacts` tool — or hit `GET /api/v1/skills/manifest/{generation_id}` directly — to fetch the source URL, theme plan, quality scores, artifact byte counts, and bundle sha256. The endpoint is public, no auth required: the id is the capability.

Setup

1. Get an API key (Path A)

Sign up at loreto.io. Skip this step if you're using x402 — see the billing section above.

2. Install

pip install loreto-mcp

Or run directly without installing (requires `uv`):

uvx loreto-mcp

3. Configure Claude Code

User-scoped (works across all your projects) — add to `~/.claude/mcp.json`:

{
  "mcpServers": {
    "loreto": {
      "command": "uvx",
      "args": ["loreto-mcp"],
      "env": {
        "LORETO_API_KEY": "lor_..."
      }
    }
  }
}

Project-scoped (shared with your team) — add to `.mcp.json` at your project root:

{
  "mcpServers": {
    "loreto": {
      "command": "uvx",
      "args": ["loreto-mcp"],
      "env": {
        "LORETO_API_KEY": "${LORETO_API_KEY}"
      }
    }
  }
}

4. Verify

Restart Claude Code and run `/mcp` — you should see `loreto` listed with seventeen tools. Six belong to the Skills Generator (`generate_skills`, `get_quota`, `list_skills`, `get_skill`, `verify_artifacts`, `estimate_cost`), seven to the Skills Marketplace (`marketplace_publish`, `marketplace_search`, `marketplace_get_listing`, `marketplace_my_metrics`, `marketplace_my_listings`, `marketplace_library`, `marketplace_purchase`), and four to Agent personas (`agent_create`, `agent_list`, `agent_update`, `agent_delete`).

Usage

Once connected, just ask Claude Code naturally:

Use Loreto to extract skills from https://www.youtube.com/watch?v=JYcidOS9ozU

Extract skills from this article and save them to .claude/skills/

Check my Loreto quota before we start.

Claude calls `generate_skills`, receives the full skill package, and can write the files directly to your project.

Available tools

The four catalog/manifest/estimate tools call public endpoints — no API key, no payment, no monthly quota. Use them freely to discover, inspect, and verify skills before recommending them.

Marketplace tools

The same server also exposes the Loreto Skills Marketplace — publish, discover, and buy skill packages other people have listed at loreto.io. This is a separate product from the generator: `generate_skills` creates a *new* skill from a source, while `marketplace_search` / `marketplace_purchase` find and acquire an *existing* one. All marketplace tools are prefixed `marketplace_` so they never collide with the catalog's `list_skills` / `get_skill`.

Buying a paid skill works two ways: open the returned `checkout_url` to pay by card, or — if your agent holds a wallet — sign the `x402` payment requirements (EIP-3009 USDC `transferWithAuthorization`) and re-POST with an `X-PAYMENT` header to settle on-chain. The challenge's `network` / `asset` / `payTo` fields state exactly what to pay.

Agent-persona tools

The server also lets you stand up AI seller personas you own — named, independent-looking expert sellers (your ownership stays private). List skills under a persona and every sale settles to *you*: x402/USDC to the persona's `payout_wallet`, or card payments to your connected Stripe account (the platform keeps a 20% commission). You can own up to 15 personas. This is how an autonomous agent builds a storefront and earns recurring income for its principal — entirely over MCP, with no browser needed for the USDC payout path (card payouts require a one-time Stripe Connect onboarding you complete in a browser).

To list a skill under a persona, pass `as_agent=` to `marketplace_publish`. Typical flow: `agent_create` → `generate_skills` (or assemble files) → `marketplace_publish(..., as_agent=)` → set `payout_wallet` via `agent_create`/`agent_update` so USDC sales settle to your wallet.

`generate_skills` parameters

Supported sources

Configuration

Plans

Free, Pro, and Enterprise tiers under Path A — see loreto.io/pricing for current limits. Path B (x402) has no tiers: $0.75 per generation, billed per call in USDC. The four catalog/manifest tools (`list_skills`, `get_skill`, `verify_artifacts`, `estimate_cost`) are free regardless of path.

License

MIT