tomasz-zajac-oss · Oct 6, 2026 · Oct 6, 2026
diff --git a/apps/web/index.html b/apps/web/index.html
@@ -63,7 +63,7 @@ <h1>Architecture that lives here,<br /><span class="accent">and holds whatever b
         <div class="tile" style="--c:#6ea8ff">
           <span class="tile-icon"><svg viewBox="0 0 16 16"><path d="M8 2v2M8 12v2M2 8h2M12 8h2M3.5 3.5l1.4 1.4M11.1 11.1l1.4 1.4M3.5 12.5l1.4-1.4M11.1 4.9l1.4-1.4" stroke="currentColor" stroke-width="1.5" fill="none" stroke-linecap="round"/><circle cx="8" cy="8" r="2"/></svg></span>
           <span class="tile-head"><span class="tile-name">Modelled by either</span></span>
-          <span class="tile-text">Draw it in Studio, chat it with AI, or let an agent edit the <code>.radical</code> file.</span>
+          <span class="tile-text">Draw it in Studio, chat it with AI, or connect your agent over <a href="#mcp">MCP</a>.</span>
         </div>
         <div class="tile" style="--c:#0e7490">
           <span class="tile-icon"><svg viewBox="0 0 16 16"><path d="M8 3C4 3 1.5 8 1.5 8S4 13 8 13s6.5-5 6.5-5S12 3 8 3Zm0 8a3 3 0 1 1 0-6 3 3 0 0 1 0 6Zm0-1.5a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3Z"/></svg></span>
@@ -114,6 +114,10 @@ <h2>Also in the box</h2>
           <span class="f-icon" style="--c:#6ea8ff"><svg viewBox="0 0 16 16"><path d="M8 2v2M8 12v2M2 8h2M12 8h2M3.5 3.5l1.4 1.4M11.1 11.1l1.4 1.4M3.5 12.5l1.4-1.4M11.1 4.9l1.4-1.4" stroke="currentColor" stroke-width="1.5" fill="none" stroke-linecap="round"/><circle cx="8" cy="8" r="2"/></svg></span>
           <span><strong>AI that edits the model.</strong> Validated, undoable patches. Claude, OpenAI, Gemini or Ollama — your key, nothing proxied.</span>
         </li>
+        <li>
+          <span class="f-icon" style="--c:#0f766e"><svg viewBox="0 0 16 16"><path d="M6 1h1.5v3H6V1Zm2.5 0H10v3H8.5V1ZM4 4.5h8V7a4 4 0 0 1-3.25 3.93V13h-1.5v-2.07A4 4 0 0 1 4 7V4.5ZM7 13.5h2V15H7v-1.5Z"/></svg></span>
+          <span><strong>MCP server.</strong> Claude Code, Claude Desktop or Codex read and edit a model folder with the same tools as Studio's assistant.</span>
+        </li>
         <li>
           <span class="f-icon" style="--c:#1e3a5f"><svg viewBox="0 0 16 16"><rect x="1" y="1" width="6" height="6" rx="1.5"/><rect x="9" y="1" width="6" height="6" rx="1.5"/><rect x="1" y="9" width="6" height="6" rx="1.5"/><path d="M11.25 9.5h1.5v2.25H15v1.5h-2.25v2.25h-1.5v-2.25H9v-1.5h2.25V9.5Z"/></svg></span>
           <span><strong>Concept Hub.</strong> 120+ ready-made requirements, ADRs, patterns and blueprints.</span>
@@ -152,6 +156,29 @@ <h2>Start from the Hub</h2>
       </div>
     </section>
 
+    <!-- ── MCP ── -->
+    <section class="install mcp" id="mcp">
+      <div class="install-text">
+        <h2>Connect your agent</h2>
+        <p>
+          A local MCP server gives Claude Code, Claude Desktop, Codex or any MCP client the model as tools:
+          read the summary and the metamodel rules, search, add and move elements, create views, sequences and slides, run Smart Layout.
+          Every write is checked against the metamodel, and Studio shows it on the open canvas.
+        </p>
+        <div class="install-links">
+          <a href="manual.html#mcp">Setup &amp; tools →</a>
+          <a href="https://github.com/radicaltools/radical.tools/tree/main/apps/mcp" target="_blank" rel="noopener">Source →</a>
+        </div>
+      </div>
+      <pre class="code"><code><span class="cm"># Node.js ≥ 20, from the repository root</span>
+npm run build -w @radical/mcp
+
+<span class="cm"># point it at a Markdown model folder</span>
+claude mcp add radical-folder -- node \
+  /path/to/radical.tools/apps/mcp/dist/index.js \
+  --folder /path/to/my-model</code></pre>
+    </section>
+
     <!-- ── Run locally ── -->
     <section class="install" id="install">
       <div class="install-text">

diff --git a/apps/web/landing.css b/apps/web/landing.css
@@ -224,6 +224,8 @@ main:not(.doc-main) > section { width: var(--w); margin: 0 auto; }
 .tile-n { margin-left: auto; font-family: var(--mono); font-size: 11px; color: var(--muted); }
 .tile-text { font-size: 12.5px; line-height: 1.5; color: var(--muted); }
 .tile-text b { color: var(--text-2); font-weight: 600; }
+.tile-text a { color: var(--accent); }
+.tile-text a:hover { text-decoration: underline; }
 
 /* ── Feature list ────────────────────────────────────────────────── */
 .features { padding: 0 0 64px; }

diff --git a/apps/web/manual.html b/apps/web/manual.html
@@ -4,7 +4,7 @@
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>Docs — Radical.Tools</title>
-  <meta name="description" content="Radical.Tools documentation: modelling with C4, DDD and governance, UI mockups and screen flows, six view kinds, milestones, presentations, Markdown-folder persistence, the metamodel editor, the Concept Hub and the AI assistant." />
+  <meta name="description" content="Radical.Tools documentation: modelling with C4, DDD and governance, UI mockups and screen flows, six view kinds, milestones, presentations, Markdown-folder persistence, the metamodel editor, the Concept Hub, the AI assistant and the MCP server for coding agents." />
   <!-- Before any stylesheet: sets data-theme for the first paint and is not blocked by a slow font CDN. -->
   <script src="theme.js?v=__BUILD__"></script>
   <link rel="preconnect" href="https://fonts.googleapis.com" />
@@ -80,6 +80,7 @@
             <li><a href="#hub">Concept Hub</a></li>
             <li><a href="#ai">AI assistant</a></li>
             <li><a href="#forge">Radical Forge</a></li>
+            <li><a href="#mcp">MCP server</a></li>
           </ul>
         </div>
         <div class="toc-group">
@@ -103,7 +104,7 @@ <h1>Radical.Tools, explained</h1>
         <p class="doc-hero-sub">
           One model of your architecture; every diagram, table and wiki page derived from it.
           This guide walks through modelling, the six view kinds, milestones, presentations,
-          files, the metamodel editor, the Concept Hub and the AI assistant.
+          files, the metamodel editor, the Concept Hub, the AI assistant and the MCP server that lets coding agents edit the model.
         </p>
         <div class="doc-hero-actions">
           <a class="cta" href="https://studio.radical.tools" target="_blank" rel="noopener">Open Studio</a>
@@ -503,6 +504,7 @@ <h2>AI assistant</h2>
           <li><strong>Change the model</strong> — “add a Redis cache between the API gateway and the accounts service”. The answer is a <em>patch</em> (add / update / delete nodes and relations, add views) that is validated against the metamodel, applied atomically and undoable like any other edit.</li>
           <li><strong>Draft governance</strong> — turn a paragraph or a <a href="#properties">need</a> into EARS requirements (linked back to the need) or an ADR with the right fields filled.</li>
         </ul>
+        <p>The same tools are available outside Studio: the <a href="#mcp">MCP server</a> hands them to Claude Code, Claude Desktop, Codex or any other MCP client.</p>
       </section>
 
       <section class="doc-section" id="forge">
@@ -517,6 +519,60 @@ <h2>Radical Forge</h2>
         </ul>
       </section>
 
+      <section class="doc-section" id="mcp">
+        <h2>MCP server</h2>
+        <p>
+          The <strong>MCP server</strong> lets a coding agent work on your model directly: <strong>Claude Code</strong>, <strong>Claude Desktop</strong>, <strong>Codex</strong> or any other client that speaks the <a href="https://modelcontextprotocol.io" target="_blank" rel="noopener">Model Context Protocol</a>. It runs locally over stdio, is bound to one <a href="#formats">Markdown folder</a>, and offers the same tools as the <a href="#ai">AI assistant</a> in Studio, so the agent can read the architecture, ADRs and requirements before it writes code and update the model when the design changes. Nothing leaves your machine except what your agent sends to its own provider.
+        </p>
+        <h3>Set it up</h3>
+        <p>Build it once with Node.js 20 or newer, from a clone of the repository (see <a href="#vscode">local install</a>):</p>
+<pre class="code"><code>npm install
+npm run build -w @radical/mcp
+node apps/mcp/dist/index.js --folder /absolute/path/to/my-model   <span class="cm"># waits for MCP messages on stdin</span></code></pre>
+        <p>Then register that command with your client, using absolute paths:</p>
+<pre class="code"><code><span class="cm"># Claude Code</span>
+claude mcp add radical-folder -- node /path/to/radical.tools/apps/mcp/dist/index.js --folder /path/to/my-model
+
+<span class="cm"># Codex</span>
+codex mcp add radical-folder -- node /path/to/radical.tools/apps/mcp/dist/index.js --folder /path/to/my-model</code></pre>
+        <p>For <strong>Claude Desktop</strong>, add it under <code>mcpServers</code> in <code>~/Library/Application Support/Claude/claude_desktop_config.json</code> (on Windows <code>%APPDATA%\Claude\claude_desktop_config.json</code>) and restart the app. Give the full path to <code>node</code>, because the app does not see your shell's <code>PATH</code>:</p>
+<pre class="code"><code>{
+  "mcpServers": {
+    "radical-folder": {
+      "command": "/usr/local/bin/node",
+      "args": ["/path/to/radical.tools/apps/mcp/dist/index.js", "--folder", "/path/to/my-model"]
+    }
+  }
+}</code></pre>
+        <h3>Working alongside Studio</h3>
+        <p>
+          Open the <em>same</em> folder in Studio: in the desktop app, or in a Chromium browser through <em>Manage models…</em> (the browser asks for folder access; a model kept only in browser storage cannot be reached by the server). Studio reloads the folder when the agent changes it, so new elements appear on the open canvas. Then ask the agent to call <code>get_model_summary</code> first; the server's instructions tell it to as well.
+        </p>
+        <div class="doc-tip">
+          <strong>Tip:</strong> while the agent writes, keep Studio in <a href="#presenting">Viewer</a>. A change spans several files and the two processes share no lock: the server refuses to write over a file that changed since it read it, but editing the same folder from both sides at once can still race.
+        </div>
+        <h3>Tools</h3>
+        <div class="doc-table-wrap">
+          <table class="doc-table">
+            <thead><tr><th>Group</th><th>Tools</th></tr></thead>
+            <tbody>
+              <tr><td><strong>Read</strong></td><td><code>get_model_summary</code> — counts, views, sequences, presentations and the metamodel rules (property keys and enum options, allowed parents, cardinality, allowed relation pairs) · <code>search_model</code> — the assistant's query language (<code>LIST NODES WHERE …</code>, <code>GET NEIGHBORS</code>, <code>LIST SEQUENCES</code>…)</td></tr>
+              <tr><td><strong>Elements &amp; relations</strong></td><td><code>add_node</code>, <code>update_node</code>, <code>delete_node</code>, <code>move_node</code> (change the parent) · <code>add_relation</code>, <code>update_relation</code>, <code>delete_relation</code></td></tr>
+              <tr><td><strong>Views</strong></td><td><code>create_view</code>, <code>update_view</code>, <code>set_view_nodes</code>, <code>delete_view</code> · <code>smart_layout</code> for All elements or one view</td></tr>
+              <tr><td><strong>Sequences &amp; slides</strong></td><td><code>create_sequence</code>, <code>update_sequence</code>, <code>delete_sequence</code> · <code>create_presentation</code>, <code>update_presentation</code>, <code>delete_presentation</code></td></tr>
+              <tr><td><strong>Metamodel</strong></td><td><code>upsert_node_type</code>, <code>delete_node_type</code>, <code>upsert_relation_type</code>, <code>delete_relation_type</code></td></tr>
+            </tbody>
+          </table>
+        </div>
+        <ul>
+          <li><strong>Validated like Studio.</strong> Writes go through the same schemas and metamodel rules as the editor; an invalid parent, type or relation pair is refused with a message the agent can act on. A tool reports success only after the files are written.</li>
+          <li><strong>Placement.</strong> New elements land inside their parent and parents grow to fit; call <code>smart_layout</code> to tidy up. New elements show in <em>All elements</em> until a view lists them (<code>create_view</code>, <code>set_view_nodes</code>).</li>
+          <li><strong>Metamodel edits.</strong> Changing a built-in metamodel saves it as a <code>…-custom</code> copy, like the <a href="#metamodel">Metamodel editor</a>. The server then re-announces the element and relation tools with the new types.</li>
+          <li><strong>Plain files.</strong> Unrelated files and the text of <code>radical.md</code> are left as they were, so the agent's changes show up as small Git diffs.</li>
+        </ul>
+        <p>Single <code>.radical</code> files, milestones, canvas-only actions (switching or focusing the view in Studio) and remote HTTP connections are not supported.</p>
+      </section>
+
       <!-- ═══════════════ REFERENCE ═══════════════ -->
 
       <section class="doc-section" id="formats">
@@ -538,7 +594,7 @@ <h3>Markdown folder</h3>
 ├─ metamodel.json · hubTemplates.json
 └─ _layout.json               <span class="cm"># positions &amp; camera — the only noisy file</span></code></pre>
         <p>
-          Each <code>.md</code> has YAML front-matter (<code>id</code>, <code>type</code>, <code>label</code>, then the element's properties, sorted) and the description as body. Hierarchy is the directory tree. Output is deterministic — sorted keys, stable file names — so Git diffs show what changed and nothing else. Edit the files by hand; the app picks them up.
+          Each <code>.md</code> has YAML front-matter (<code>id</code>, <code>type</code>, <code>label</code>, then the element's properties, sorted) and the description as body. Hierarchy is the directory tree. Output is deterministic — sorted keys, stable file names — so Git diffs show what changed and nothing else. Edit the files by hand, or let an agent edit them through the <a href="#mcp">MCP server</a>; the app picks them up.
         </p>
       </section>
 
@@ -593,7 +649,8 @@ <h3>Desktop app</h3>
 npm run dev              <span class="cm"># Electron, hot reload</span>
 npm run build &amp;&amp; npm start
 npm run dev:web          <span class="cm"># browser build of Studio</span>
-npm run dev:hub          <span class="cm"># Architecture Hub</span></code></pre>
+npm run dev:hub          <span class="cm"># Architecture Hub</span>
+npm run build -w @radical/mcp   <span class="cm"># MCP server for coding agents</span></code></pre>
         <p>The desktop app adds native file dialogs, Markdown folders without browser permissions and <code>--file</code> watching. Everything else is identical to the browser build.</p>
       </section>