Q360 MCP Server

Connect Claude, ChatGPT, or any other MCP-compatible AI to your Q360 Quality Management System. No config-file editing required.

The server exposes ~287 tools across documents, CAPA, NCR, audits, risks, training, suppliers, compliance mappings, scheduled tasks, evidence, SPC, surveys, approvals, and cross-module workflows — always scoped to a single organization.

Pick your install path

Q360 supports three ways to connect. Pick the one that matches your client.

| Client | Recommended install | Time to first prompt | |---|---|---| | Claude Desktop (macOS/Windows) | Download the .dxt extension, double-click | ~30 sec | | Claude Code (CLI) | npx q360-mcp-server setup | ~20 sec | | ChatGPT / any remote client | Host the server and add the URL | ~5 min |

All three paths ship a single API key that scopes you to exactly one Q360 organization, with read and/or write scopes you control. The server enforces both at startup and on every tool call.

Option A — Claude Desktop, one-click (.dxt)

1. Open Q360 → Workspace Settings → API Keys → "Connect Claude Desktop". Q360 builds a pre-configured .dxt file with your broker URL embedded and your API key baked in.
2. Double-click the downloaded q360-<version>.dxt file. Claude Desktop opens, shows the extension manifest, and asks you to confirm.
3. Claude Desktop prompts for any missing secrets (e.g. the API key if you chose not to embed it).
4. Click Install. Done.

No JSON editing. No path hunting. The extension appears in Claude Desktop → Settings → Extensions and can be disabled or removed from there.

Behind the scenes the .dxt is a tiny zip: dxt/manifest.json tells Claude Desktop what to run, dxt/launcher.js shells out to npx q360-mcp-server so the server is always the freshest published version, and user_config in the manifest is what drives the prompts Claude Desktop shows.

Building the .dxt yourself

git clone https://github.com/NickBuete/q360 && cd q360/q360-mcp-server
npm install && npm run build
npm run build:dxt        # produces q360-1.3.0.dxt in the package root

Ship the resulting file to users or bundle it into your Q360 onboarding emails.

Option B — Claude Code / any terminal, one command

npx q360-mcp-server setup

This runs an interactive installer that:

1. Prompts for the broker URL and API key (or reads them from Q360_BROKER_URL / Q360_API_KEY if already set).
2. Writes the right Claude Desktop config file for your OS (macOS, Windows, or Linux/XDG), preserving any MCP servers you already have configured.
3. Detects the claude CLI and runs claude mcp add q360 ... for you if it's installed.
4. Tells you to restart Claude Desktop or relaunch Claude Code, and suggests a first prompt.

Non-interactive mode (for CI / scripting)

npx q360-mcp-server setup \
  --non-interactive \
  --broker-url="https://<project>.supabase.co/functions/v1/mcp-broker" \
  --api-key="q360_..." \
  --claim-token="claim_..."   # optional

Useful flags:

| Flag | Effect | |---|---| | --non-interactive | Never prompts; fails if a value is missing. | | --skip-claude-desktop | Don't touch the Claude Desktop config. | | --skip-claude-code | Don't run claude mcp add. |

Option C — ChatGPT and other remote clients (HTTP transport)

For ChatGPT custom connectors, Claude web "Remote MCP servers", or any hosted agent, run the server as a streamable-HTTP service and give the AI the URL.

Host it locally (dev / single user)

npx q360-mcp-server --http --port 3333
# → Q360 MCP server listening at http://127.0.0.1:3333/mcp
#   Health: http://127.0.0.1:3333/health

The same Q360_BROKER_URL / Q360_API_KEY env vars authenticate the server at startup. The HTTP endpoint is stateless — a fresh MCP session is spun up per request — so you can safely run multiple clients against it.

Host it remotely (team / production)

Deploy the built dist/ directory to any container host (Fly.io, Render, ECS, Cloud Run) with the env vars set:

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY dist ./dist
ENV PORT=3333
EXPOSE 3333
CMD ["node", "dist/index.js", "--http", "--host=0.0.0.0", "--port=3333"]

Then in ChatGPT → Custom Connectors → Add → paste the HTTPS URL and any Bearer token header your deployment requires for ingress. In Claude (web or desktop) → Settings → Connectors → Remote → paste the URL.

Security note: The built-in HTTP transport binds to 127.0.0.1 by default and applies a basic DNS-rebinding Origin check for loopback deployments. For public exposure, terminate TLS at a reverse proxy, require a per-client ingress credential, and re-check the Origin header at your ingress layer.

What it exposes

| Domain | Representative tools | |---|---| | Documents | qms_list_documents (paginated), qms_create_document, qms_submit_document_for_review, qms_approve_document, qms_publish_document, qms_acknowledge_document, qms_compare_document_versions | | Standards & clauses | qms_list_standards, qms_enable_standard, qms_set_primary_standard, qms_list_standard_requirements, qms_create_clause_equivalence | | CAPA / NCR / Risk / Audit | qms_list_capas / ncrs / risks / audits (paginated), create/update variants, qms_add_audit_finding, qms_list_audit_findings | | Cross-module | qms_create_capa_from_finding, qms_create_ncr_from_event, qms_link_records, qms_get_entity_links | | Approvals | qms_get_pending_approvals, qms_submit_for_approval, qms_approve_record, qms_reject_record | | Analytics | qms_get_compliance_summary, qms_get_campaign_analytics, qms_list_report_runs | | Evidence & scheduling | qms_create_evidence, qms_list_evidence, qms_create_scheduled_task, qms_list_scheduled_tasks | | Operational depth | Forms, audit programs, equipment, calibration, inspections, process maps, SPC, surveys, controls, compliance mappings, complaints, customer feedback, training, suppliers, supplier lots, webhooks, email templates, exports, retention, SLAs, signatures |

Every tool is registered via the modern registerTool API with title, description, inputSchema, outputSchema-ready envelopes, and inferred annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint). Clients that auto-approve read-only tools will auto-approve any qms_list_* / qms_get_* / qms_search_* without prompting.

Environment variables

| Variable | Required | Purpose | |---|---|---| | Q360_BROKER_URL | yes (broker mode) | URL of the mcp-broker edge function in your Q360 Supabase project. | | Q360_API_KEY | yes (broker mode) | Your workspace API key. Resolves the organization and scopes at startup. | | Q360_CLAIM_TOKEN | optional | One-shot token emitted when an admin provisions a new MCP connection. On first successful startup, the server calls claim_connection to bind this installation to the connection record in Q360. | | SUPABASE_URL | dev only | Direct-mode fallback — see "Hardening" below. | | SUPABASE_SERVER_KEY / SUPABASE_SERVICE_ROLE_KEY | dev only | Direct-mode fallback — see "Hardening" below. |

Scopes

When you generate an API key in Q360 you pick the scopes it grants:

| Scope | What it allows | |---|---| | read | All qms_list_*, qms_get_*, qms_search_*, qms_verify_* tools | | write | All creates, updates, deletes, approvals, publications, acknowledgements |

A key without write scope will receive a clear error (not a silent drop) if the agent tries to mutate data. Rotate keys regularly; revoking a key immediately terminates all sessions using it.

Architecture

Claude Desktop / Claude Code / ChatGPT
  ↕ (MCP protocol: stdio or streamable HTTP)
q360-mcp-server
  ↕ (HTTPS, Bearer Q360_API_KEY)
Q360 mcp-broker edge function  (hosted Supabase function)
  ↕ (Supabase service role, server-side only)
Supabase PostgreSQL
  → controlled_documents, capas, non_conformities, audits, risks, ...
  → RLS policies enforce organization_id scoping

The broker validates the API key, resolves the organization and scopes, and injects organization_id = :resolved_org on every non-global table query. Tools registered in this server cannot reach data outside the caller's organization — resolveOrgId() in src/helpers.ts rejects any attempt to override the bound org via an explicit organizationId parameter.

Hardening path

Broker mode (recommended — default for all production deployments)

• End-user machine holds only an org-scoped API key (q360_...).
• SHA-256 hash resolves to {organization_id, scopes} at startup.
• Every subsequent request flows through the hosted broker, which is the only caller holding the privileged database credentials.
• API keys can be rotated or revoked without touching end-user machines.

Direct mode (development only — do not ship to users)

If Q360_BROKER_URL is unset but SUPABASE_URL + SUPABASE_SERVER_KEY are set, the server falls back to direct Supabase access using a server-side key. This mode requires distributing a privileged service-role key and bypasses RLS at the DB layer. Use it only for local development against a dev Supabase instance.

Commands

# Interactive, one-command install
npx q360-mcp-server setup

# Non-interactive install
npx q360-mcp-server setup --non-interactive --broker-url=... --api-key=...

# Run as local stdio server (what Claude Desktop and Claude Code launch)
npx q360-mcp-server

# Run as HTTP server for remote clients
npx q360-mcp-server --http --port 3333

# Show help
npx q360-mcp-server --help

# Show version
npx q360-mcp-server --version

Development

npm install
npm run build          # compile TypeScript
npm run dev            # watch + rebuild
npm test               # build + run Node test runner suite
npm run build:dxt      # package the Claude Desktop .dxt extension

The test suite includes integration tests for the document lifecycle, standards enablement, pagination envelopes, annotation inference, and the setup / Claude Desktop config merge logic — all using FakeServer + FakeSupabase, no network required.

What's in this release (1.3.0)

• One-click install for Claude Desktop via .dxt extension (see dxt/).
• One-command install for Claude Code via npx q360-mcp-server setup.
• Remote HTTP transport for ChatGPT and any other MCP-over-HTTP client (--http).
• 287 tools migrated to the modern server.registerTool(...) API with inferred readOnlyHint, destructiveHint, idempotentHint, openWorldHint annotations and a human-readable title per tool.
• Three previously-orphaned tool modules (analytics, approvals, crossModule) are now wired up — +18 tools.
• Pagination envelopes on the five hero list tools (qms_list_documents, qms_list_capas, qms_list_ncrs, qms_list_risks, qms_list_audits) with limit / offset / hasMore / nextOffset.
• CHARACTER_LIMIT truncation on paginated responses to protect the agent's context window.
• Postgres-aware error formatting (formatSupabaseError) so RLS / FK / unique-constraint errors come back as actionable English.

Full audit + migration plan: AUDIT.md. Evaluation template: evaluation.xml.

License

Proprietary. All rights reserved.