HelloZen Read-Only MCP

HelloZen MCP 2.0 — configuration auditor release (v2.0.0 on branch feat/configuration-auditor). See CHANGELOG.md and docs/configuration-auditor.md. Tag v1.1.1 remains the prior stable baseline.

An unofficial, self-hosted, strictly read-only MCP connector designed for inspecting HelloZen configuration.

Use this connector with Cursor (trusted LAN), ChatGPT (via OpenAI Secure MCP Tunnel), or MCP Inspector to review custom fields, pipelines, calendars, and workflows when planning integrations for a photography studio on HelloZen — without exposing contact data or write access.

Disclaimer: This project is unofficial and is not affiliated with, endorsed by, or supported by HelloZen unless explicitly approved by the HelloZen owner. Do not use HelloZen logos or imply official partnership.

This connector cannot create, update or delete HelloZen data. Its credential contains no write scopes, and its application transport rejects every method except GET.

What it does

A small read-only Model Context Protocol server that exposes selected HelloZen / LeadConnector configuration data to trusted AI clients. The HelloZen Private Integration token remains on the server; MCP clients never receive it.

Exposes 13 read-only MCP tools (four original inventory tools preserved, plus auditor tools):

Every tool response includes freshness metadata (meta.source, meta.fetchedAt, meta.cacheAgeMs). Pass fresh: true to bypass cache. See docs/configuration-auditor.md.

It does not access contacts, conversations, appointments, opportunity records, emails, form submissions, calendar events, or workflow enrolments.

Related MCP server: appstoreconnect-codex-mcp

Architecture

                 trusted private LAN (no Internet route to MCP)

Cursor (workstation) ──────────────────────┐
                                           ▼
                              http://<host>:8790/mcp
                                           ▲
ChatGPT ──► OpenAI Secure MCP Tunnel ──► tunnel-client (private host)
                                           │
                                           ▼
                              hellozen-mcp (Docker, on-demand)
                                           │
                              server-side read-only token
                                           ▼
                                   HelloZen API (GET only)

There is no public HelloZen MCP endpoint. Do not port-forward TCP 8790.

Client paths

Cursor — trusted private LAN

Cursor
   ↓
http://<host-lan-ip>:8790/mcp
   ↓
hellozen-mcp

ChatGPT — OpenAI Secure MCP Tunnel

ChatGPT
   ↓
OpenAI Secure MCP Tunnel
   ↓
tunnel-client (on private host)
   ↓
http://<reachable-mcp-address>:8790/mcp
   ↓
hellozen-mcp

On a typical Vision deployment, Cursor and tunnel-client use the same private host address (HELLOZEN_MCP_PUBLISH_HOST). Both clients may stay connected to one running MCP listener concurrently.

This connector does not provide a public MCP endpoint, OAuth resource server, or general Internet-facing API.

Security model (v1.1)

• HelloZen API access is read-only (four fixed GET endpoints only)

• The HelloZen Private Integration token is server-side only — never supply it to MCP clients, ChatGPT, or Cursor

• Secrets live in .env on the deployment host; .env is gitignored and must never be committed

• Responses are normalized and data-minimized; logs are sanitized

• Rate limits, concurrency limits, and response size caps are enforced

• There are no HelloZen write tools

• Assumes trusted private LAN or OpenAI Secure MCP Tunnel access to the MCP HTTP endpoint

• Does not implement OAuth or a public Internet-facing MCP endpoint

• The LAN HTTP endpoint is not suitable for public Internet exposure

For on-demand availability and defence-in-depth rationale, see SECURITY.md.

Documentation

Read-only security model

Application boundary

• Only GET requests to four fixed LeadConnector endpoints

• Hard-coded upstream origin: https://services.leadconnectorhq.com

• No arbitrary URLs, methods, or query strings

• Response size capped while streaming (~2 MB)

• Tokens and raw upstream payloads never appear in logs, errors, or tool output

Credential boundary

Create a dedicated HelloZen Private Integration for this connector. Required scopes:

locations/customFields.readonly
opportunities.readonly
calendars.readonly
workflows.readonly

Do not grant:

• Any .write permission

• Contacts permissions

• Calendar Events permissions

• Conversations permissions

• Edit, Create, Manage, or Delete permissions

Never use HELLOZEN_PRIVATE_INTEGRATION_TOKEN or reuse write-capable credentials from other projects.

Residual risk

The opportunities.readonly scope is relatively broad in HighLevel because it covers both pipeline configuration and opportunity reads. This connector only calls the pipelines list endpoint, but a compromised token could still be misused outside this connector if broader API access was granted. Use the narrowest scopes possible.

Requirements

• Node.js 22+

• A HelloZen sub-account location ID

• A read-only Private Integration token

Tested against

• ChatGPT MCP connectivity using internal OpenAI Tunnel

• Cursor local unauthenticated local network access

Local development

git clone <your-repo-url> hellozenmcp
cd hellozenmcp
npm install
cp .env.example .env
# Edit .env with your read-only token and location ID
npm run dev

Health check:

curl http://127.0.0.1:8790/healthz

MCP Inspector

Point MCP Inspector at:

http://127.0.0.1:8790/mcp

Verify HelloZen connectivity

Run manually after configuring .env (not during container startup):

npm run verify:hellozen

Example output:

Custom fields: accessible, 12
Pipelines: accessible, 3
Calendars: accessible, 2
Workflows: accessible, 8

This command prints counts only — no credentials, raw responses, or customer information.

Docker

The connector is on-demand. It is not designed to run continuously. See On-demand operation below.

Initial build and container creation (generic example):

cp .env.example .env
# Edit .env on the deployment host only — never commit credentials
docker build --pull -t hellozenmcp-hellozen-mcp .
docker compose up -d --no-build hellozen-mcp

On hosts where docker compose build works (Buildx >= 0.17.0), you may use docker compose up -d --build instead of the two-step build above.

The default compose file publishes on loopback only via HELLOZEN_MCP_PUBLISH_HOST (default 127.0.0.1):

${HELLOZEN_MCP_PUBLISH_HOST:-127.0.0.1}:8790:8790

Set HELLOZEN_MCP_PUBLISH_HOST in .env on the deployment host for trusted-LAN access — do not edit compose.yml and do not use 0.0.0.0.

Docker is configured with restart: "no", so a host or Docker daemon reboot does not automatically start the connector.

For operator-specific deployment paths, copy DEPLOYMENT.local.md.example to DEPLOYMENT.local.md (gitignored).

On-demand operation

The MCP connector is intentionally not a continuously running service. Its normal resting state is STOPPED. Starting it requires an explicit operator action. This is a deliberate security control — see SECURITY.md.

Expected lifecycle:

STOPPED normally
    ↓
./scripts/hellozen-session start
    ↓
MCP healthy + tunnel ready (when configured)
    ↓
Cursor and/or ChatGPT inspection session
    ↓
./scripts/hellozen-session stop
    ↓
STOPPED

Session commands (recommended)

./scripts/hellozen-session status   # MCP + tunnel state, no secrets
./scripts/hellozen-session start    # start MCP, then tunnel if not ready
./scripts/hellozen-session stop     # stop owned tunnel, then MCP
./scripts/hellozen-session doctor   # tunnel-client diagnostics

npm aliases: npm run session:status, session:start, session:stop, session:doctor.

Manual MCP commands

cd /mnt/user/devconcepts/hellozenmcp
docker compose ps

Start an existing container

docker compose start hellozen-mcp

If the container has not yet been created

docker compose up -d --no-build hellozen-mcp

Confirm healthy

docker compose ps
curl -fsS http://127.0.0.1:8790/healthz && echo

Stop after the ChatGPT/HelloZen session

docker compose stop hellozen-mcp

Use docker compose stop for normal shutdown. You do not need docker compose down for routine sessions — stop preserves the container so the next session can use docker compose start.

After a Vision or Docker daemon reboot, the connector remains stopped until you explicitly start it again.

Cursor setup

Cursor can connect directly to the MCP over Streamable HTTP on a trusted LAN.

Add a server entry to your Cursor MCP configuration (for example ~/.cursor/mcp.json or project .cursor/mcp.json). Use the URL transport — no HTTP authentication headers are required:

{
  "mcpServers": {
    "hellozen": {
      "url": "http://192.168.50.234:8790/mcp"
    }
  }
}

Replace 192.168.50.234 with the LAN address of the host running hellozen-mcp. That address is deployment-specific — it is shown here only as the current Vision host example, not as a portable default.

Before relying on Cursor:

1. Start the MCP container: docker compose start hellozen-mcp

2. Confirm health from a machine that can reach the host:

curl -fsS http://<host-lan-ip>:8790/healthz && echo

Cursor direct access requires Docker (or the Node process) to publish port 8790 on an interface reachable from your workstation — see Docker networking.

ChatGPT setup

ChatGPT connects through the OpenAI Secure MCP Tunnel. High-level operator sequence:

1. Start hellozen-mcp
2. Verify MCP health (/healthz)
3. Start the OpenAI tunnel-client on the Vision host
4. Point the tunnel upstream at an MCP address reachable from that host
5. Verify tunnel readiness (/readyz on the tunnel health port)
6. Configure the ChatGPT custom MCP app (Tunnel connection, no authentication)

Full setup guide: docs/connecting-to-chatgpt.md

Useful verification commands (replace addresses as appropriate):

docker compose ps
curl -fsS http://<reachable-mcp-address>:8790/healthz && echo
curl -fsS http://127.0.0.1:8791/readyz && echo

The tunnel upstream URL must match an address where the MCP is actually listening. A healthy Docker container does not guarantee ChatGPT connectivity if the tunnel points at the wrong interface — see Troubleshooting.

Docker networking

Host publish address (HELLOZEN_MCP_PUBLISH_HOST) controls which host interface receives MCP traffic. This is distinct from HELLOZEN_MCP_BIND_HOST (in-container listen address, default 0.0.0.0).

Committed default (safe for local dev and host-only tunnel):

ports:
  - "${HELLOZEN_MCP_PUBLISH_HOST:-127.0.0.1}:8790:8790"

Vision / trusted LAN — set in gitignored .env:

HELLOZEN_MCP_PUBLISH_HOST=192.168.50.234

Then use the same endpoint for Cursor and tunnel-client:

http://192.168.50.234:8790/mcp

Do not set publish host to 0.0.0.0. Do not port-forward TCP 8790 to the Internet.

Document deployment-specific values in gitignored DEPLOYMENT.local.md.

Troubleshooting

Symptom: ChatGPT returns 502; tunnel /readyz returns 503; Docker shows healthy

docker compose ps may report the MCP container as healthy while ChatGPT still cannot reach the service.

Likely cause: tunnel upstream points to a different host interface than Docker is listening on.

Example mismatch:

Docker listening:  192.168.50.234:8790
Tunnel upstream:   http://127.0.0.1:8790/mcp

Fix: configure the tunnel upstream URL to an address where the MCP is actually reachable from the process running tunnel-client. Verify with:

curl -fsS http://<upstream-host>:8790/healthz && echo

from the same host that runs the tunnel.

Do not expose the MCP on the public Internet without authentication.

Symptom: Cursor cannot connect

• Confirm the MCP is started (docker compose ps)

• Confirm port 8790 is published on an interface reachable from your workstation

• Confirm curl to http://<host>:8790/healthz succeeds from the Cursor machine

OpenAI Secure MCP Tunnel

Do not expose this service on a public port. Connect via OpenAI Secure MCP Tunnel after local verification.

Full setup guide: docs/connecting-to-chatgpt.md — repository preparation, Docker hardening, on-demand MCP, tunnel-client installation, doctor checks, ChatGPT app configuration, and operating procedures.

Option A — tunnel client on the host (Vision default)

Publish MCP on the private LAN IP. Configure the tunnel upstream and Cursor to the same URL, for example:

http://192.168.50.234:8790/mcp

Option B — tunnel client in Docker

Place hellozen-mcp and the tunnel client on a private internal Docker network. Do not publish the MCP port to the host. Configure the tunnel to target:

http://hellozen-mcp:8790/mcp

Warning: Never bind the MCP server to a publicly accessible interface without an approved authentication and authorization layer.

Tunnel setup commands and credentials are configured separately when you deploy the tunnel.

Environment variables

Credential rotation and incident response

1. Revoke the compromised Private Integration in HelloZen immediately

2. Create a new integration with the same read-only scopes

3. Update .env on the deployment host

4. Start the container when needed: docker compose start hellozen-mcp

5. Run npm run verify:hellozen to confirm access

6. Review container logs for unusual tool activity (logs contain event metadata only, not payloads)

Development commands

npm test
npm run typecheck
npm run build
npm audit

License

MIT — see LICENSE.

Security

See SECURITY.md for vulnerability reporting.