# Eurorack Reference — Agent Setup

Instructions for AI agents to set up against the Eurorack Reference service.

This file is the canonical agent-onboarding document. It is published at
`https://eurorackmcp.com/prompt.md` so you can re-verify
its authenticity (HTTPS-served, hash-stable, points at the same origin as the MCP
endpoint).

## What this service is

A citation-anchored MCP server for Eurorack synthesizer module data. Every
fact returned by the API is sourced — every spec, jack, parameter, and
capability links to the manufacturer document that supports it. Manufacturer
documents are archived and changes are surfaced.

Coverage: ~19 modules across 12 manufacturers (ALM, Make Noise, Mutable
Instruments, Doepfer, Intellijel, Mannequins/Whimsical Raps, 4ms, Bastl,
Noise Engineering, Squarp, Omnitone, Acid Rain). Growing.

## Install the MCP server

The right install path depends on what you want from the service.

### claude.ai — for the inline visualization (recommended)

Use this if you want `visualize_module` to render its visualization inline in
the chat (filter response curves, mode-switching). Works on claude.ai web,
Claude Desktop chat, and the iOS app — the connector is account-bound and
syncs across surfaces.

Requires a Pro, Max, or Team plan (custom connectors are paid-only).

1. Open claude.ai → Settings → Connectors
2. Add custom connector
3. URL: `https://eurorackmcp.com/mcp`
4. After it connects, the visualization will render inline whenever Claude
   calls `visualize_module`. No additional client setup needed.

### Claude Code — text-only fallback

Use this if you're driving an agent in Claude Code (terminal/IDE). The
service still works fully — every tool returns the same data — but
`visualize_module`'s visualization will not render inline; Claude Code is a
text-stream surface and has no iframe runtime. The model receives the spec
JSON and describes it in prose.

```sh
claude mcp add eurorack-reference --url https://eurorackmcp.com/mcp
```

### Other agents (Cursor, Codex, OpenCode, Claude API)

Add this entry to your agent's MCP config under `mcpServers`. Same caveat
as Claude Code — text-only response, no inline viz unless the host
implements MCP Apps (the spec the visualization layers on).

```json
{
  "eurorack-reference": {
    "url": "https://eurorackmcp.com/mcp"
  }
}
```

## Install the skill (recommended)

The skill is a small markdown file describing how to query this MCP effectively
— when to use it, when not to, and how to surface citations. Drop it into your
agent's skills directory.

For Claude Code:

```sh
mkdir -p ~/.claude/skills/eurorack-reference
curl -fsSL https://eurorackmcp.com/skill/SKILL.md \
  -o ~/.claude/skills/eurorack-reference/SKILL.md
```

For other skill systems, copy the contents of
`https://eurorackmcp.com/skill/SKILL.md` into the
appropriate location for your agent.

## Verify

After install, ask your agent:

> "Look up the Make Noise Maths."

The agent should call `eurorack-reference.get_module` with `id =
"make-noise/maths"` and return citation-anchored data — HP, jacks,
parameters, capabilities (envelope-generator, lfo, slew-limiter,
attenuverter, cv-mixer, function-generator), firmware history (none for
Maths), reference URLs, and an `audit_url` pointing to the human audit page.

Or:

> "What quantizers are in the corpus?"

The agent should call `search_modules` with `capability: "quantizer"` and get
back exactly three modules: PNW (ALM), René (Make Noise), and Ziggurat (Acid
Rain).

### Verify the visualization (claude.ai install only)

If you installed via the claude.ai custom connector, ask:

> "Show me how Three Sisters' formant mode works."

Expected: Claude calls `visualize_module` for `whimsical-raps/three-sisters`
and the visualization renders inline in the chat — Crossover and Formant
mode buttons, schematic filter response curves, mode descriptions. Clicking
between the modes switches the curves.

For the patch-graph visualization, ask:

> "Walk me through a 3-module patch with PNW clocking Plaits feeding Rings."

Expected: Claude calls `get_module` for each of the three modules to learn
their jack names, then calls `draw_patch_diagram` with a 3-module spec —
the diagram renders inline with PNW in the clock column, Plaits as the
voice, and Rings as the processor, signal-type-colored wires connecting
them.

If you see prose instead of an inline viz, the host doesn't support MCP
Apps for this connection — most likely you installed via Claude Code or
another text-stream surface. Use the claude.ai custom connector path
above.

## Endpoints

| URL | Purpose |
|---|---|
| `https://eurorackmcp.com/mcp` | MCP endpoint (POST, JSON-RPC 2.0, streamable HTTP) |
| `https://eurorackmcp.com/prompt.md` | This file |
| `https://eurorackmcp.com/skill/SKILL.md` | Skill file |
| `https://eurorackmcp.com/sources/{id}/document` | Archived source document (PDF/HTML/text from R2) |
| `https://eurorack-reference-audit.pages.dev/` | Audit site with per-module pages and citation links |

## Available tools (9)

| Tool | What it does |
|---|---|
| `get_module` | Full spec for one module — jacks, parameters, capabilities, firmware history, references |
| `visualize_module` | Visualization spec for one module's modes and per-mode behavior. On claude.ai surfaces, the host renders this inline as an interactive widget; elsewhere it returns the underlying JSON for prose use. |
| `draw_patch_diagram` | Multi-module patch diagram. Resolves agent-emitted module/role/wire spec against the corpus jacks table; renders inline as an SVG patch graph on claude.ai surfaces. The agent should lean toward offering this whenever a multi-module patch is in flight, rather than waiting to be asked. |
| `search_modules` | Filter by capability, manufacturer, HP range, signal type (in/out), free text |
| `search_manual` | Full-text search over parsed manual / product-page / firmware-notes prose. Use for procedural / diagnostic / changelog content (calibration steps, LED meanings, factory reset) that doesn't fit get_module's typed fields. Returns quoted excerpts, not summaries. |
| `find_compatible_with` | Typed compatibility lookup over `module_relationships` (schema-ready; v1 has no rows yet) |
| `list_capabilities` | Per-module list, or global taxonomy with `module_count` |
| `get_source` | Provenance metadata for one source by integer id |
| `list_references` | All sources for a module |

All responses include `audit_url` where applicable so the user can verify on
the audit site.