AskRefinedElement.Mcp 0.2.0

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 (.NET)

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 package is the .NET delivery surface: a NuGet-published dnx tool that stands up the same six tools as a stdio MCP server. (A TypeScript/npm sibling exists too — see Related Projects — so agents can reach the pack from either ecosystem.) It is also a working example of the agent-ready CMS pattern the pack itself describes.

Most of the pack is free. A few knowledge items are premium, gated behind an L402 (Lightning) payment of 100 sats — a working demonstration of metered, pay-per-access content on the same content model. Which items are premium is decided in the CMS, so search flags them as [PREMIUM] rather than this README naming them. Everything else, including a priority-flagged consultation (request_consultation with priority: true), is free.

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, Sentinel rules, and premium playbooks on Kentico upgrades, GEO, AI development, Sentinel, and CMS architecture.
• Browse the whole index — call search with no query to get every item grouped by content type, with slugs, so the agent can see what exists before it picks a search term.
• 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 so Mike sees the urgency. Both are free.
• 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

Premium items and their slugs are discovered through search_refined_element_knowledge (they are flagged [PREMIUM]) — the catalog is owned by the CMS, so it can grow without a package release. topic and audience filters accept any string and are matched exactly against each result; known topic values today (examples) are kentico-upgrades, geo, ai-development, sentinel, cms-architecture, and known audience values are developer, marketer, decision-maker, agent.

Requirements

• .NET 10 SDK — it ships the dnx command used to run the server. If your client reports "The command dnx … was not found", install the .NET 10 SDK.
• 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 (dnx is the .NET analogue of npx; it downloads the tool from NuGet and runs it):

dnx AskRefinedElement.Mcp --yes

Claude Code

claude mcp add ask-refined-element -- dnx AskRefinedElement.Mcp --yes

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

{
  "mcpServers": {
    "ask-refined-element": {
      "command": "dnx",
      "args": ["AskRefinedElement.Mcp", "--yes"]
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "ask-refined-element": {
      "command": "dnx",
      "args": ["AskRefinedElement.Mcp", "--yes"]
    }
  }
}

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 premium items (see below).

The L402 Payment Flow

Premium knowledge items are 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. A credential you already paid for stays valid — on any transient hiccup, retry with the same macaroon and preimage; you never pay twice. 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, build, and run the tests:

git clone https://github.com/refined-element/ask-refined-element-dotnet.git
cd ask-refined-element-dotnet
dotnet build -c Release
dotnet test  -c Release   # xUnit — stubs HttpClient, 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 dnx AskRefinedElement.Mcp --yes

# Or run straight from source (no packaging step)
ASK_RE_BASE_URL=http://localhost:23917 dotnet run --project src/AskRefinedElement.Mcp

In a client config, set it under env:

{
  "mcpServers": {
    "ask-refined-element": {
      "command": "dnx",
      "args": ["AskRefinedElement.Mcp", "--yes"],
      "env": { "ASK_RE_BASE_URL": "http://localhost:23918" }
    }
  }
}

To package the NuGet tool locally:

dotnet pack -c Release   # → src/AskRefinedElement.Mcp/bin/Release/AskRefinedElement.Mcp.0.2.0.nupkg

Project structure

ask-refined-element-dotnet/
├── src/AskRefinedElement.Mcp/
│   ├── Program.cs                  # stdio host entry point (logs to stderr)
│   ├── AskRefinedElementTools.cs   # [McpServerToolType] — the six tools + descriptions
│   ├── AskTools.cs                 # tool logic + response formatting (transport-free)
│   ├── AskReClient.cs              # public HTTP client (10s timeout covers the body read)
│   ├── HttpOutcome.cs              # discriminated request outcome (never throws)
│   ├── ApiTypes.cs                 # API response shapes
│   └── .mcp/server.json            # MCP server manifest (NuGet reads this)
├── tests/AskRefinedElement.Mcp.Tests/
│   └── *.cs                        # xUnit
├── README.md
└── LICENSE

Related Projects

• Ask Refined Element (npm) — the TypeScript/Node sibling of this server; identical tools, for the npm/npx ecosystem.
• 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.