Part of Refined Element — an independent consultancy for Xperience by Kentico upgrades, AI-driven development, and agent-first marketing (GEO).

Ask Refined Element MCP Server

An open-source MCP (Model Context Protocol) server that lets AI agents query Refined Element's knowledge pack: field-tested guidance on Xperience by Kentico upgrades, GEO (generative engine optimization), AI-driven development, Sentinel for Xperience by Kentico, and agent-ready CMS architecture.

The knowledge pack is authored once in Xperience by Kentico and served headless — to humans on the website, to AI crawlers via llms.txt, and to agents through this MCP server. This server is one of those delivery surfaces, and a working example of the agent-ready CMS pattern the pack itself describes.

Most of the pack is free — including priority consultation requests. Two knowledge items are premium, gated behind a single L402 (Lightning) payment of 100 sats — a demonstration of metered, pay-per-access content on the same content model.

What It Does

Give your AI agent this server and it can:

• Search the knowledge pack — ranked, answer-first summaries it can cite directly, across blog articles, FAQs, case studies, services, checklists, and premium playbooks on Kentico upgrades, GEO, AI development, Sentinel, and CMS architecture.
• Fetch a full checklist — complete, ordered, actionable steps by slug (e.g. the GEO readiness checklist).
• Read the blog — list recent Refined Element articles and read any one in full, with its HTML converted to clean text (headings, lists, and links preserved).
• Request a consultation — send a message straight to Mike Rahel; set priority: true to flag it as urgent (free — no payment).
• Buy a premium playbook — retrieve an L402-gated item: the tool returns the Lightning invoice on the first call, then the full content once the agent has paid.

Tools

| Tool | Paid | What you get | |------|------|--------------| | search_refined_element_knowledge | Free | Ranked matches with answer-first summaries across articles, FAQs, case studies, services, checklists, and playbooks. Article hits point at get_article; premium hits are flagged with their price and the slug to buy them. | | get_checklist | Free | One full free checklist by slug — title, summary, topic, audience, and every ordered step. | | list_articles | Free | Recent blog articles, newest first — title, publish date, one-line summary, url, and the slug to read each in full. | | get_article | Free | One full blog article by slug — HTML converted to readable text (headings, lists, and links preserved), plus its canonical URL. | | request_consultation | Free | Send a consultation request to Mike Rahel. Set priority: true to flag it as urgent — still free, no payment. | | get_paid_playbook | 100 sats (L402) | One premium item by slug. First call returns a Lightning invoice + macaroon; a second call with the paid credential returns the full content. |

search_refined_element_knowledge

Full-text search over the pack. Returns ranked matches, each with an answer-first summary you can cite directly or use to decide which item to fetch in full. Premium items return a summary and slug only — get their body with get_paid_playbook. Free checklists can be pulled in full with get_checklist.

{
  "query": "kentico upgrade risk",
  "topic": "kentico-upgrades",       // optional filter
  "audience": "decision-maker",       // optional filter
  "limit": 5                          // optional, default 5, max 20
}

topic and audience accept any string and are matched exactly against each result — the taxonomy is owned by the CMS, so new values keep working without a package upgrade. Known topic values today (examples): kentico-upgrades, geo, ai-development, sentinel, cms-architecture. Known audience values today (examples): developer, marketer, decision-maker, agent. Only query is required.

get_checklist

Fetch one full free checklist by slug, e.g. geo-readiness-checklist-basic. Returns the complete ordered step list — each step with its one-line action and an explanatory sentence — ready to follow, quote, or hand to a user. If the slug is a premium checklist, the response points you to get_paid_playbook. Unknown slugs return a not-found result.

{ "slug": "geo-readiness-checklist-basic" }

list_articles

List the most recent posts from the Refined Element blog, newest first. Each entry has its title, publish date, a one-line summary, the canonical URL, and the slug to read it in full with get_article.

{ "limit": 10 }   // optional, default 10, max 50

get_article

Read one full blog article by slug (discover slugs with list_articles or search_refined_element_knowledge). Returns the title, publish date, summary, the complete body converted from HTML to readable text — headings, lists, and links preserved — and the canonical URL. Unknown slugs return a not-found result.

{ "slug": "agent-ready-cms-xperience" }

request_consultation

Send a consultation request straight to Mike Rahel — for Xperience by Kentico upgrades, AI-driven development, or agent-first (GEO) work. The email is shape-checked locally (a quick @/length sanity check) and fully validated by the API.

{
  "name": "Ada Lovelace",
  "email": "[email protected]",
  "message": "We need help upgrading a KX13 site to Xperience by Kentico.",
  "company": "Analytical Engines Ltd",  // optional
  "priority": false                      // optional; true = flag as urgent (free)
}

Mike reads every request personally, so include enough context for him to act on it. Set priority: true to flag the request as urgent so Mike sees the urgency — priority is free, no payment required.

get_paid_playbook (L402-gated)

Retrieve one premium item by slug, gated at 100 sats via L402. Discover the current premium items and their slugs with search_refined_element_knowledge — they are flagged [PREMIUM]. (Examples at the time of writing: agent-ready-cms-checklist-full, kentico-upgrade-risk-triage — the CMS owns the catalog, so this list can grow without a package release.)

{
  "slug": "kentico-upgrade-risk-triage",
  "macaroon": "…",   // omit on the first call
  "preimage": "…"     // omit on the first call
}

See The L402 payment flow below.

Requirements

• Node.js ≥ 22.
• The Ask Refined Element API (/api/ask/*) must be live at the configured base URL. The default is the production site, https://refinedelement.com. If the API is not reachable there — for example while it is still being deployed, or when you run the site locally — point the server at the right host with the ASK_RE_BASE_URL environment variable (see Development). When the base URL answers with an HTML page instead of API JSON, the tools report that the API is not deployed/reachable there rather than pretending content does not exist.

Quick Install

Run it with no install:

npx -y ask-refined-element-mcp

Claude Code

claude mcp add ask-refined-element -- npx -y ask-refined-element-mcp

Or add it to .mcp.json in your project:

{
  "mcpServers": {
    "ask-refined-element": {
      "command": "npx",
      "args": ["-y", "ask-refined-element-mcp"]
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "ask-refined-element": {
      "command": "npx",
      "args": ["-y", "ask-refined-element-mcp"]
    }
  }
}

Config file locations:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

No API key, wallet, or secret is needed to install or run this server — it calls only public endpoints. A Lightning wallet is needed only to unlock the two premium items (see below).

The L402 Payment Flow

Two knowledge items are premium and gated with L402 — the HTTP 402 "Payment Required" standard for pay-per-access over Lightning. get_paid_playbook handles both halves of the exchange:

1. Ask for the item. Call get_paid_playbook with only the slug. The endpoint answers 402 Payment Required with a Lightning invoice (100 sats) and a macaroon. The tool returns these as structured payment instructions — it does not error.
2. Pay the invoice. Pay the Lightning invoice with any wallet that returns a payment preimage. The easiest path for an agent is the free Lightning Enable MCP server and its pay_invoice tool — connect a wallet via NWC or Strike (docs.lightningenable.com) and it pays, tracks, and budgets automatically.
3. Unlock the content. Call get_paid_playbook again with the same slug plus the macaroon from step 1 and the preimage from step 2. The tool sends Authorization: L402 <macaroon>:<preimage> and returns the full item.

If a credential fails to verify, the tool returns a fresh challenge with the same guidance, so the agent can retry cleanly. Run both the Lightning Enable MCP and this server together and an agent can discover, pay for, and read a premium playbook end to end without a human in the loop.

Development

Clone, install, build, and run the smoke tests:

git clone https://github.com/refined-element/ask-refined-element.git
cd ask-refined-element
npm install
npm run build      # tsc → dist/
npm test           # vitest — mocks fetch, asserts each tool + the 402 flow

Run against a local Ask Refined Element API instead of production with the ASK_RE_BASE_URL environment variable:

# Default is https://refinedelement.com
ASK_RE_BASE_URL=http://localhost:23918 npx -y ask-refined-element-mcp

# The local re-xbk app may serve the API on :23918 or :23917
ASK_RE_BASE_URL=http://localhost:23917 node dist/index.js

In a client config, set it under env:

{
  "mcpServers": {
    "ask-refined-element": {
      "command": "node",
      "args": ["/absolute/path/to/ask-refined-element/dist/index.js"],
      "env": { "ASK_RE_BASE_URL": "http://localhost:23918" }
    }
  }
}

npm run dev runs the TypeScript entry point directly via tsx without a build step.

Project structure

ask-refined-element/
├── src/
│   ├── index.ts    # stdio entry point (bin)
│   ├── server.ts   # MCP server + tool registration (zod schemas)
│   ├── tools.ts    # tool logic + response formatting
│   ├── api.ts      # public HTTP client (10s timeout, clean error shaping)
│   └── types.ts    # API response shapes
├── test/
│   └── tools.test.ts
├── package.json
├── tsconfig.json
└── LICENSE

Related Projects

• Lightning Enable MCP — give your agent a Lightning wallet; pays L402 challenges (including this server's premium items) automatically.
• Lightning Enable — infrastructure for agent commerce over Lightning.
• Lightning Enable Docs — wallet setup (NWC, Strike) and the full L402 guide.

Links

• Refined Element — the consultancy, and the live knowledge pack.
• Sentinel for Xperience by Kentico — the free, open-source Kentico health scanner referenced throughout the pack.

License

MIT © Refined Element, LLC — see LICENSE.