Quickstart

Get a real MCP server running in under ten minutes. You’ll install the rune CLI, scaffold a from-scratch server with one model, and exercise the auto-generated polymorphic tool set through the MCP Inspector — no database, no API backend, no auth setup.

The Rails analogy: one declaration, one fan-out.

Add a second model and the same nine tools serve it too — that’s the “polymorphic” promise; the LLM’s tool list does not grow with your domain.

Install the CLI

The rune CLI scaffolds new mcp-rune projects, runs them under the MCP Inspector, and manages their lifecycle. Install it globally:

npm install -g @mcp-rune/create

Prefer no global install? npx @mcp-rune/create new … and npm create @mcp-rune@latest … work the same way; see the CLI README for the one-shot forms.

Scaffold a server

Create a server from scratch with the simple preset (stdio transport, no database, CRUD on the models you declare):

rune new my-server --preset simple --models Book
cd my-server
npm install

Run interactively without flags and the wizard’s single question — “How would you like to start?” — defaults to Quick start (the same simple preset). Pass --yes to accept every default; pass --models Book,Tag to scaffold more than one model. The full prompt/flag matrix lives in the CLI README.

Then open the project in the MCP Inspector:

rune inspect

The Inspector opens in your browser, pre-wired to your scaffolded server. You’re now connected to a working MCP server with one model (Book), the default prompt strategy, and all nine polymorphic tools registered.

Try a tool

Verified against rune CLI 0.11.0 · @mcp-rune/mcp-rune 0.107.0 · Node 24.

Inside the Inspector, call these three in order. Each one reads the Book declaration directly — no backend wiring needed — so the output below should match exactly.

1. list_models with {} — discovers the book schema.

[
  {
    "name": "book",
    "endpoint": "books",
    "description": "A Book record",
    "attributes": ["name", "description"],
    "required_attributes": ["name"],
    "read_only": false
  }
]

2. get_prompt_guide with { "guide_name": "book" } — the auto-generated creation guide an LLM reads to fill the form. Every word of it is derived from src/models/book.ts; no template lives anywhere else.

3. validate_form with { "model": "book", "fields": {} } — structured validation feedback for an empty submission:

{
  "valid": false,
  "ready_to_submit": false,
  "errors": [{ "field": "name", "message": "Name is required" }],
  "warnings": [],
  "computed": {},
  "fields": {}
}

Call it again with { "model": "book", "fields": { "name": "Dune" } } and it flips to "valid": true, "ready_to_submit": true. Same code path, driven by the required: true flag on the name attribute.

Three tools, zero backend code, all derived from the four-line attributes: block. That’s the polymorphic promise.

Want a fuller demo?

The bookshelf example template ships with three seed books, the full polymorphic tool set, interactive MCP apps, an optional 5,000-book corpus for analysis strategies (distribution, coverage, anomaly, temporal, entity-extraction), and optional GraphRAG wiring — zero external setup. Scaffold it instead of (or alongside) my-server:

rune new bookshelf-demo --template bookshelf

See the CLI README · Templates section for the full template list and the mcp-rune/examples/bookshelf source for what the template generates.

Connect to Claude Desktop

To talk to the same server from Claude Desktop, drop this block into claude_desktop_config.json:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["tsx", "/abs/path/to/my-server/src/server.ts"]
    }
  }
}

Replace /abs/path/to/my-server with the absolute path to the scaffolded project (the simple-preset entry point lives at src/server.ts). Restart Claude Desktop and the my-server server will appear in the tool picker.

What you got

From a single model declaration in my-server/src/models/book.ts, the framework registered the polymorphic tool set:

• Data (CRUD) — list_models, find_records, create_model, update_model, delete_model, bulk_action_models
• Form strategy — get_prompt_guide, validate_form, get_form_summary

The three form-strategy tools and list_models work out of the box because they read the Book declaration directly. The other five data tools route through an ApiClient, which the simple preset deliberately leaves as a throwing Proxy stub — try find_records({"model":"book"}) and you’ll see the seam: “No ApiClient configured. Wire createApiClient in src/config.ts before using auth-gated tools.” That error is the pointer to the next chapter, not a bug.

Add a second model with rune add model Tag --attrs name:string,color:string (or scaffold with --models Book,Tag from the start) and the same nine tools serve it too. For interactive MCP apps, analysis, GraphRAG, and HTTP+OAuth transport, scaffold the advanced preset or the bookshelf template above.

Going further

Replace the stub ApiClient in src/config.ts with a real createApiClient factory and the same tools, prompts, and apps light up against your backend without touching the model declaration. Three guides walk the wiring: API configuration for the static api block every CRUD call reads, API client for the HTTP contract, and Data layer (“Swapping the Adapter”) for the swap pattern itself.

Next

• Analysis Quickstart — Part 2: bring up pgvector with one docker compose block, point the bookshelf at the 5,000-book dataset, and exercise every summary strategy through analysis_ingest + analysis_summarize.
• Project structure — where models, prompts, tools, apps, and the domain registry live in a generated mcp-rune project.
• Prompt creation — the DSL that turns model attributes into agent-fillable forms.
• MCP apps — interactive HTML UIs rendered inside Claude Desktop.
• Data layer — the seam between the projection layer and any concrete data backend (in-memory, HTTP, custom).