Zuar Portal — MCP Server

Let Claude operate your Zuar Portal (zPortal) for you — author HTML blocks, build pages, manage data sources, queries, themes and users, explore real data, and keep a git-versioned, revertible history of every change, all through natural language.

An MCP server that exposes a Zuar Portal's REST + auth APIs to any MCP client (Claude Desktop, Claude Code, …). It turns "build me a sales dashboard" into the right sequence of authenticated calls — discover data sources → write a saved query → author a validated HTML block → bind it → place it on a page — with bundled authoring guidance, layered write-safety, and a revertible history.

git clone https://github.com/patrickdeanfox/zuar-portal-mcp.git ~/zuar-portal-mcp
cd ~/zuar-portal-mcp && npm install && npm run build
claude mcp add zuar-portal --scope user -- node ~/zuar-portal-mcp/dist/index.js

At a glance

flowchart TB
    CD["<b>MCP Client</b><br/>Claude Desktop · Claude Code · any MCP client"]
    CD -- "JSON-RPC / stdio" --> S

    subgraph server["zuar-portal-mcp server"]
        direction TB
        S["index.ts → buildServer()"]
        S --> BT["🧱 <b>Block tools</b><br/>typed authoring + place_blocks"]
        S --> RT["📦 <b>Resource tools</b><br/>generic CRUD · 18 kinds (blocks included)"]
        S --> AT["⚡ <b>Action tools</b><br/>query · profile · users · config"]
        S --> VC["🕓 <b>Version-control tools</b><br/>snapshot · history · diff · restore"]
        S --> EL["🪄 <b>Setup &amp; design</b><br/>configure_project · synthesize_theme"]
        G{{"🛡️ <b>Safety &amp; integrity gates</b><br/>write-domain · structure · refs · impact · SQL"}}
        BT & RT & AT & VC & EL --> G
    end

    G --> HTTP["portalClient.ts<br/>login · X-Api-Key · retry · circuit breaker"]
    HTTP -- "/api + /auth · HTTPS" --> P[("Zuar Portal")]
    BT -. "mirrors every content write" .-> GIT[("git VC repo<br/>revertible")]

    classDef gate fill:#fde68a,stroke:#b45309,color:#000;
    class G gate

Every write is tagged with a risk domain and passes the safety gates before anything reaches the portal; every successful content write is mirrored to a git repo so it can be reverted.

Related MCP server: AutoWP MCP Server

Contents

• Highlights

• What Claude can do with it — the 38-tool catalog

• The Claude Code agent ecosystem — pipeline, agents, model/effort routing

• Guided onboarding & theming (elicitation)

• Requirements & credentials

• 🖱️ Install — Claude Desktop (one-click)

• ⌨️ Install — Claude Code & other clients

• Per-project configuration (multiple portals)

• Getting started

• Write safety & tool gating

• Resilience, observability & hardening

• Troubleshooting · Security · License

Working on the server rather than with it? See CONTRIBUTING.md.

Highlights

What Claude can do with it

40 tools — one uniform surface ("a resource is a resource") across 11 capability groups. The full per-tool reference is generated from the live server (npm run gen:docs, so it can't drift): docs/03 · Tools Reference.

🧱 Block tools — typed + validated

Blocks are now a first-class registry kind: list, fetch, and delete them with the generic resource tools (resource: "block"), and the block-authoring rules run as a per-kind validator at the registry write chokepoint — create_resource (block) is validated exactly like create_block. The typed fronts remain for ergonomic authoring:

File input [4.2.0] — create_block, update_block, and validate_block take html_file and css_file. The server reads the bytes, so a model never carries them. Retyping a large block into a tool call is not a copy but a re-transcription: it burns tokens and silently normalizes characters (an em dash inside a regex character class arriving as a hyphen changes what the pattern matches — and passes review). Pass a path instead, edit the file in place, and only the delta is ever transcribed. Every gate runs identically either way. Reads are contained to the CWD, the VC dir, and any PORTAL_FILE_ROOTS entry. | bind_block_query | Bind a block to a datasource/query (auto-creates the query); sets ui_queries. | | place_blocks | One declarative placement primitive — add, update, hide, or remove blocks on a page grid in a single atomic write. mode: "merge" appends/updates (and honours remove: [...]); mode: "replace" + confirm: true makes the page exactly the given list while preserving survivors' customized grid.layouts and hidden flags. |

Pass resource plus a body/id. Call describe_resource to see each resource's fields, required-to-create fields, supported verbs, and risk domain.

Covered resources: block, layout (pages), datasource, query, db_modification, partial, theme, snippet, translation, dashboard, tag, user, group, permission, access_policy, api_key, credential, system.

Every write tool accepts dry_run: true — every gate runs (domain, structure, per-kind rules, references, impact), nothing is written, and the response carries applied: false plus what would have been written.

The current user's profile is plain resource CRUD now: get_resource / update_resource with resource: "user", id: "me". Guided migration scoping is the migration_kickoff prompt (see Prompts below).

See docs/07 · Version Control.

Resources (zportal://guide/*) — authoring guidance Claude reads before building, so blocks follow zPortal conventions even on a fresh machine: block-structure, currentblock, zportal-api, charting, conventions, design-system, visual-verification, migration-1.18, loading-overlay, migration-playbook, and block-performance.

Prompts — guided workflows now live here rather than in the tool surface (9): zuar_portal_start (the cheapest session opener — confirm the connection in one call, report one line, ask what's next), zuar_portal_quickstart (orient → route), create_zportal_block (discover → build → create), setup_zuar_project (connect this folder, routes to configure_project), migrate_block_to_118 (one legacy block → the 1.18 lifecycle), add_loading_overlay (the sanctioned spinner + fade-out), block_perf_pass (the large-dataset perf audit: measure → trim SELECT * → chart-lib prefetch → 60 s honest timeouts), design_intake (guided theming — walks brand/website/density/radius, drives synthesize_theme, then creates the theme via create_resource), and migration_kickoff (guided migration scoping — batches the scope decisions, writes .zuar-portal/migration-scope.json, then runs migration_preflight).

The Claude Code agent ecosystem

When this repo is your Claude Code working directory, the MCP tools come with a team of specialists in .claude/. You don't drive create_block/bind_block_query by hand — you describe what you want, and a gated pipeline builds, styles, hardens, and reviews it. Full guide: docs/13 · Agents & Workflows.

The block pipeline

Blocks are never shipped raw. A spec flows through quality gates, each a focused subagent:

flowchart LR
    spec([spec]) --> B["🏗️ builder"] --> St["🎨 stylist"] --> R["📱 responsive"] --> D["🔧 debugger"]
    D --> A{"🚨 adversary<br/><b>CODE GATE</b>"}
    A -- "blocking (≤2 rounds)" --> D
    A -- "clean" --> V{"👁️ visual<br/><b>GATE</b>"}
    V -- "blocking (≤2 rounds)" --> D
    V -- "clean / skipped" --> Ad["🧭 advisor"] --> ship([ship ✅])

    classDef gate fill:#fde68a,stroke:#b45309,color:#000;
    classDef ro fill:#dbeafe,stroke:#1d4ed8,color:#000;
    class A,V gate
    class Ad ro

The adversary (gate) red-teams the block and proves each finding with evidence; while it returns blocking findings the pipeline loops back to the debugger. The visual gate (the adversary with browser eyes) then opens the rendered block in Claude for Chrome — screenshot, console, network — and a blank render, console error, sample-not-live data, or overflow loops back to the debugger too; it's best-effort and skips with a note when the extension isn't connected or the block isn't on a page. The advisor asks "is this the right block?" All gates are read-only — they carry no write tools and physically cannot mutate the portal (browsing/screenshotting is read-only). Beyond the six pipeline agents, four specialists handle broader jobs: portal-data-expert, portal-theme-designer, portal-bulk-operator (snapshot-first), and portal-onboarding.

Seeing the portal (Claude for Chrome)

Every gate above reasons about a block from its code and query rows — but a block can validate, bind, and still render blank, throw a runtime console error, overflow its grid cell, or silently show its hardcoded sample fallback instead of live data. With the Claude for Chrome extension connected, the agents can see the portal: open the page, screenshot the block, and read the browser console/network — for visual debugging and a final visual sign-off.

• Recorded at setup. configure_project asks whether you use Claude for Chrome and stores browser.claudeInChrome in ./.zuar-portal/config.json; get_capabilities reports it.

• Used where it pays. The debugger looks before it guesses; the adversary owns the visual gate; the stylist and responsive-specialist screenshot their work (the latter steps widths with resize_window); the advisor checks it reads at a glance.

• Sign-in caveat. The MCP authenticates with an API key, but the browser needs a logged-in session — to view private pages you must be signed into your portal in Chrome. The MCP can't log you in.

• Graceful by design. No extension, or the block isn't on a page? Every agent falls back to code-only review and says so. The doctrine lives in the zportal://guide/visual-verification resource.

Slash commands

Model & effort routing

Each agent runs on the model and reasoning effort that fit its job — sharp where judgment matters, cheap where the work is mechanical. Three composing layers:

1 · Agent defaults (model:/effort: frontmatter) — for a direct call (a fast surgical edit, or one agent dispatched from a command):

2 · Workflow tier toggle — portal-block-pipeline.js and portal-audit.js take args:{ …, tier } and set each stage's model/effort explicitly:

3 · Commands pin to sonnet · medium — they only orchestrate (pre-flight → dispatch → synthesize); quality lives in the agents/workflow they call. /portal-build and /portal-audit infer the tier from your phrasing.

The MCP server never selects a model — only the agents, commands, and workflows that drive it do. Re-tier via agent frontmatter or a workflow's ROUTING table; see .claude/README.md.

Guided onboarding & theming (elicitation)

On a client that supports elicitation (Claude Desktop, Claude Code), configure_project prompts you field-by-field instead of making you hand-edit JSON — and validates everything live before committing. Guided theming is now the design_intake MCP prompt, which orchestrates the pure synthesize_theme tool. If the client can't prompt, configure_project falls back to argument-only mode (interactive: false).

flowchart TB
    subgraph setup["🔌 configure_project — connect a portal"]
        direction TB
        s1["Portal URL"] --> s2["API key 🔒"] --> s3["User ID"] --> s4{"add GitHub VC?<br/>(optional)"}
        s4 --> s4b{"use Claude for Chrome?<br/>👁️ visual checks"}
        s4b --> s5["✓ live portal login<br/>✓ GitHub token + repo (API)"] --> s6[["writes .zuar-portal/config.json<br/>+ .gitignore"]]
    end
    subgraph intake["🎨 design_intake prompt — theme the portal"]
        direction TB
        d1["brand + website"] --> d2["fetch site 🛡️ SSRF-guarded<br/>→ suggest brand colors"] --> d3["palette · density · radius"]
        d3 --> d4["header + sidebar style"] --> d5{"confirm?"} --> d6[["synthesize_theme →<br/>create_resource (theme)"]]
    end

• configure_project refuses to clobber an existing config, validates with a real login, and writes a gitignored ./.zuar-portal/. It also asks whether you use Claude for Chrome (stored as browser.claudeInChrome) so the build pipeline can see your blocks render — visual debugging + a final visual gate (see Seeing the portal). The setup_zuar_project prompt and /portal-setup route to it; pass interactive: false for the direct, no-prompt path. (Replaces v2's setup_portal and init_project_config.)

• The design_intake prompt fetches the brand's website through synthesize_theme's SSRF-guarded fetch to suggest a palette, then walks density/radius/header/sidebar and, on your confirmation, creates a theme resource via create_resource. synthesize_theme itself is pure — it returns the token map and the exact create_with call, and never writes.

Requirements

• A Zuar Portal reachable over HTTPS, with an account that can manage blocks (admin recommended).

• Node.js 18+ — for Claude Code and any other MCP client. (Claude Desktop's one-click .mcpb bundles its own Node, so you need nothing.)

Getting your portal credentials

You need three values, entered once during install.

Install — Claude Desktop (one-click)

1. Download zuar-portal-mcp.mcpb from the latest release.

2. Double-click it, or drag it onto the Claude Desktop window. An install dialog appears.

3. Fill in Portal URL, Portal API Key, Portal User ID (and optionally the write-safety toggles).

4. Confirm. The tools, resources, and prompts are now available to Claude.

To update later, install a newer .mcpb over the old one.

Install — Claude Code & other MCP clients

This server speaks MCP over stdio, so any MCP-capable client can use it. Clone it, build it once, and register the built entry point — you need Node ≥ 18 and git.

Register it once, for every project:

git clone https://github.com/patrickdeanfox/zuar-portal-mcp.git ~/zuar-portal-mcp
cd ~/zuar-portal-mcp
npm install
npm run build
claude mcp add zuar-portal --scope user -- node ~/zuar-portal-mcp/dist/index.js

To update: pull and rebuild in place. The path doesn't change, so there's nothing to re-register — but restart your client, since the tool list is only fetched at handshake.

cd ~/zuar-portal-mcp && git pull && npm install && npm run build

Then, in each portal project folder, connect it to that portal:

mkdir ~/work/acme-portal && cd ~/work/acme-portal
claude
> /portal-setup

/portal-setup asks for your three values, checks them with a real login, and writes a gitignored ./.zuar-portal/config.json. Every folder can point at a different portal — see Per-project configuration ↓.

.mcp.json in the project (or claude_desktop_config.json) — point args at your clone's built entry point, as an absolute path (~ is not expanded here):

{
  "mcpServers": {
    "zuar-portal": {
      "command": "node",
      "args": ["/Users/you/zuar-portal-mcp/dist/index.js"]
    }
  }
}

Per-project configuration (multiple portals)

One MCP install can drive a different portal — and a different git state-repo — in every folder. At startup the server resolves credentials in layers, highest priority first:

flowchart LR
    A["1 · Project config<br/><code>./.zuar-portal/config.json</code><br/>(walks up from cwd)"] --> R{{"resolved<br/>credentials"}}
    B["2 · Environment<br/><code>PORTAL_*</code> env vars<br/>(Desktop / MCPB)"] --> R
    C["3 · Bundle config<br/><code>config.json</code> beside bundle"] --> R

Most settings resolve per field, so a project file can set just vc.dir and inherit the rest. Empty values are ignored, so a blank Desktop field never shadows a project value.

The file uses one schema for both the portal and its VC repo:

{
  "portal": { "url": "https://team-a.zuarbase.net", "apiKey": "…", "userId": "…" },
  "vc":     { "dir": "/path/to/team-a-state", "push": true,
              "remote_url": "https://github.com/you/team-a-portal-state.git", "token": "…" }
}

Set it up without hand-editing JSON: ask Claude to run configure_project (see Guided onboarding ↑). get_capabilities shows which portal/repo is in effect under its config key (secrets redacted). ./.zuar-portal/ is gitignored, so credentials are never committed.

Getting started

New portal? Start here. From the folder you want to work in:

cd ~/work/acme-portal
claude
> /portal-setup

One command. It connects the folder to the portal (writing gitignored credentials + a binding fingerprint), profiles your datasources, interviews you about the business, and writes a project brief the other agents read. Everything below assumes it's done.

Then just talk to Claude:

1. Confirm the connection — "List the datasources on my portal." → list_resource (datasource).

2. Look at real data — "Show me a few sample rows from the Sales datasource." → profile_datasource (per-column stats + raw sample rows, so Claude sees the real column names first).

3. Create a block — "Create a stat-card block 'Total Orders' showing the order count from Sales." → reads zportal://guide/*, builds the two-field block, create_block, reports the UUID.

4. Iterate — "Make the number bigger and use the portal's primary color." / "Turn it into a bar chart of orders by state." → update_block.

Write safety & tool gating

Every write is tagged with a risk domain, gated independently:

• PORTAL_READONLY=1 disables every write — reads and discovery still work.

• A blocked write returns a clear message naming the flag to set; nothing reaches the portal.

• run_db_modification additionally requires confirm: true on every call.

• Deletes and user/password mutations are marked destructive to MCP clients.

• Uniform dry_run: true (v3.0.0) on every write tool — all gates run (domain, structure, per-kind rules, references, impact) but nothing is written; the response reports applied: false and what would have changed. A dry run never bypasses a gate.

Least-privilege tool scoping (v2.5.0) — disable whole capability groups with PORTAL_DISABLE_TOOLS=users,config, or stand up a build-only allowlist with PORTAL_ENABLE_TOOLS=blocks,resources,data (deny wins).

Upgrading from 2.x — PORTAL_COMPAT_TOOLS=1 (off by default) registers the removed v2 tool names as deprecated aliases in a compat group; each alias forwards to the same gated v3 handler, so aliases confer no extra capability.

Integrity gates (v2.5–2.6, server-side, cannot be bypassed) — every content write is checked for portal-compatible structure (a page missing grid.layouts is repaired or rejected) and dangling references; deletes run pre-delete impact analysis and refuse to orphan dependents unless force=true; user deletes refuse to remove the last admin; unscoped mass SQL (a destructive verb without a real WHERE — 1=1 doesn't count — plus MERGE/TRUNCATE/DROP/ALTER…DROP/GRANT) needs allow_unfiltered=true, and the check fails closed when the SQL can't be inspected. Run the read-only validate_portal anytime to sweep for problems. Full guide: docs/16 · Safety & Integrity.

Unattended-loop safety (unreleased) — the guarantees that make parallel/overnight agent loops safe to leave alone:

• No duplicate creates: a create that fails ambiguously (network died after the request may have landed) is verified by name and adopted if it already exists — never blindly resent. run_db_modification is never auto-retried at all.

• No lost updates: pass expected_updated_at (from your read) to update_resource / update_block / place_blocks and a mid-flight change by anyone else refuses with a conflict instead of silently overwriting.

• No stranded cruft: name loop temporaries TMP · <purpose> (or tag them scratch), then sweep with cleanup_scratch — dry-run by default, deletes only unreferenced non-recent candidates through the gated path, content stays VC-restorable.

• Provable improvement: score_portal scores every block/page 0–100 on the mechanically checkable and diffs against a saved baseline — a loop's regression is a per-record delta, not an anecdote.

• Admin can't self-destruct: stripping your own admin access needs allow_self_lockout=true; update_config and change_password require confirm (config edits return previous_at_path for one-call revert).

In the Claude Desktop bundle these are install-dialog toggles; for other clients set them as env vars. Deeper dive: docs/14 · Tool Gating & Guidance.

Resilience, observability & hardening

Production-grade behaviour for a local, single-user server — safe defaults, no configuration required.

Resilience (the portal HTTP client every tool calls through):

Retry safety: GET retries on any transient signal; writes retry only on explicit 429/503 back-pressure or a network failure that provably never connected — never on an ambiguous 502/504, and a create whose network error may have delivered the request is verified by name and adopted rather than resent (no silent duplicates).

Observability — every call gets a request id, latency, and an error tally. get_metrics (always-on) reports per-tool counts, error rate, latency, uptime, and the breaker state — metadata only, no payloads or secrets. Set PORTAL_LOG_FORMAT=json for structured stderr logs; PORTAL_AUDIT_LOG appends metadata-only JSONL for every content/data/admin write.

Output secret redaction — secret-bearing fields (password, secret, token, api_key, …) are masked as [redacted] on resource reads, so they never flow into the model's context, and secrets are also caught by shape inside any value or name — connection-string passwords (postgresql://user:[redacted]@host), JWTs, PEM private keys, AWS key ids — including in execute_query / profile_datasource results. Generic hex and key=value shapes are deliberately not masked (uuids, git shas and SQL params are legitimate content that round-trips back into writes). Identifier *_id fields are never masked; create/update responses are intact (so a freshly generated secret can be seen once). Disable with PORTAL_REDACT_SECRETS=0. Portal-authored content additionally returns inside an untrusted-data envelope, so a poisoned record name reads as data, not instructions.

Troubleshooting

More: docs/12 · Troubleshooting.

Security

• Credentials are never logged. Debug output (gated by PORTAL_DEBUG=1) goes to stderr only, so it never corrupts the MCP stdio stream.

• The API Key and User ID are declared sensitive in the bundle manifest.

• The server talks only to the Portal URL you configure; the base URL is validated as a well-formed http(s) origin at startup. synthesize_theme's website fetch (driven by the design_intake prompt) is SSRF-guarded.

• create_block / update_block are restricted to type: "html" and reject other types before any portal call.

• Secret-bearing fields are redacted from reads; tool inputs and request bodies are size-capped.

See SECURITY.md for the full posture: the per-tool-group data-touch matrix, credential handling, network egress, and data retention.

License

MIT.