v4.1.1 — confirm the portal in one call

Installing? Download zuar-portal-mcp.mcpb below and double-click it. Claude Desktop asks for three portal values — no terminal, no config files.

This is the first release since v1.0.0. Versions 2.x, 3.0.0 and 4.0.0 shipped to main but were never tagged or released, so the previous "latest release" was three majors behind what the README documents. If you installed from a release before today, you were running v1.0.0 — this brings the one-click bundle up to current code.

A session opens in one call

Confirming a portal connection took three calls — get_capabilities (~4 KB of JSON describing the server, which never dials the portal), get_version, then a user/me read for the identity.

Worse: the one call three separate documents advertised as confirming connectivity could not fail. get_version swallowed both its requests to null, so a dead portal, an expired API key and a typo'd URL all reported success. Bad credentials only surfaced at the first write.

check_connection

One authenticated round-trip. ~230 characters against get_capabilities' ~3,950:

{ "connected": true, "portal": "analytics.acme.com", "url": "https://analytics.acme.com",
  "version": "1.19.2", "signed_in_as": "pfox@acme.com", "binding": "single",
  "writes": "content", "browser_assist": false }

/auth/me is the probe because it forces the lazy login — so the credentials are genuinely exercised, not just echoed from config. It also returns the signed-in identity get_capabilities could never answer (it holds only the user UUID).

Failure returns the portal's real reason and an actionable fix:

{ "connected": false, "portal": "analytics.acme.com",
  "reason": "Portal GET /auth/me failed: HTTP 401 - invalid api key",
  "fix": "The portal rejected the credentials. Re-run configure_project (overwrite=true)..." }

An unconfigured folder reports as setup (fix → configure_project), not as breakage.

zuar_portal_start prompt

The kickoff, surfaced as a slash command by MCP clients: call check_connection, report one line, ask what's next. Costs nothing until invoked.

Also in this release

• get_version can fail again — /api/version errors are no longer swallowed. /api/about stays best-effort, so a portal that doesn't serve it still returns a usable version.
• One-call preflight everywhere — check_connection also returns url and browser_assist, the other two reasons agents fetched the 4 KB posture dump. Every /portal-* command, all 10 specialist agents, the block pipeline and the generated project CLAUDE.md now use the small call.
• The server reports its real version — SERVER_VERSION was a hardcoded literal stuck at 3.0.0 through the entire 4.0.0 release, so every client's serverInfo named a build that hadn't shipped in months. Now read from package.json. (The test that should have caught it asserted only version.length > 0; it now pins to package.json.)
• Documentation drift, found by audit and fixed — SECURITY.md omitted an always-on tool that makes an authenticated call and returns the signed-in identity; docs/14 documented the retired start sequence; docs/02 told operators to verify an install with the call that couldn't fail; the agent tools: allowlists granted get_version but not check_connection, which would have left the new call unreachable; portal-block-stylist claimed get_capabilities reports theme tokens (it never has); the README version badge said 3.0.0.
• block_perf_pass was registered but never advertised in the manifest — added, plus a prompt-parity test.

Upgrading

Drop-in from 4.0.0 — no breaking changes. Nothing is removed; get_capabilities remains for the full tool/group, VC and audit posture.

Full changelog: https://github.com/patrickdeanfox/zuar-portal-mcp/blob/main/CHANGELOG.md