Q360 MCP Server

An MCP (Model Context Protocol) server that gives Claude direct access to the full Q360 workspace. Clients can use it to manage multi-standard document control, evidence, audits, risks, CAPAs, scheduling, surveys, SPC, equipment, calibration, compliance mappings, and related end-to-end QMS workflows through natural conversation.

What This Does

When connected, the server exposes tool groups spanning the live QMS surface:

| Module | What Claude Can Do | |--------|--------------------| | Documents | Create documents, manage version history, submit for review, approve, publish, acknowledge, and link evidence | | Standards | Enable standards, set a primary standard, and inspect standard requirements | | Evidence & Scheduling | Manage evidence records and scheduled task workflows | | Audits, NCRs, CAPAs, Risks, Objectives | Operate the core assurance and improvement workflows | | Forms & Audit Programs | Maintain form templates/submissions/schedules and audit programs | | Operational Modules | Work with equipment, calibration, inspections, process maps, SPC, surveys, and compliance mappings |

Setup

1. Install and Build

cd q360-mcp-server
npm install
npm run build

2. Get Your Supabase Credentials

From your Supabase project dashboard (Settings > API):

• SUPABASE_URL: https://kljkytscetwfrszoexqi.supabase.co
• SUPABASE_SERVER_KEY: A trusted server-side Supabase key. The current package still uses the service-role key unless you front it with your own broker/RPC layer.

3. Connect to Claude Desktop

Add this to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "q360": {
      "command": "npx",
      "args": ["-y", "q360-mcp-server"],
      "env": {
        "Q360_BROKER_URL": "https://kljkytscetwfrszoexqi.supabase.co/functions/v1/mcp-broker",
        "Q360_API_KEY": "your-workspace-api-key-here"
      }
    }
  }
}

4. Connect to Claude Code

claude mcp add q360 -e Q360_BROKER_URL="https://kljkytscetwfrszoexqi.supabase.co/functions/v1/mcp-broker" -e Q360_API_KEY="your-workspace-api-key-here" -- npx -y q360-mcp-server

Usage

Once connected, talk to Claude naturally. If Q360_API_KEY is configured, organization scoping happens automatically. Without it, tools require an explicit organizationId.

Example prompts:

"List all my open CAPAs"

"Create a new document control policy, submit it for review, approve it, and publish the controlled copy."

"Enable ISO 9001 and ISO 27001 for this workspace, then show me the enabled standard requirements."

"Create evidence for the last internal audit and link it to the relevant document and scheduled task."

"I need to raise a non-conformity report for a temperature excursion in the production area. Severity is Major."

"Show me all risks with a probability of Likely or higher"

"Create a training record for John Smith on specialized procedures — schedule it for next Monday, 2 hours"

"What change requests are currently submitted and waiting for approval?"

Architecture

Claude Desktop / Claude Code
  ↕ (MCP protocol over stdio)
q360-mcp-server
  ↕ (Supabase JS client, service role)
Supabase PostgreSQL
  → controlled_documents, capas, audits, risks, etc.
  → RLS policies scope all data to organization_id

The server currently uses a trusted Supabase server key to bypass RLS (since the MCP server talks to the database directly). Q360_API_KEY resolves organization context and now enforces read / write scope at runtime. If you do not provide Q360_API_KEY, every tool call must include organizationId.

This means the package is safer than the original direct-service-role setup, but it is not yet a fully de-privileged client architecture. Removing the privileged key entirely still requires a hosted broker or SECURITY DEFINER RPC layer.

Development

npm run dev    # Watch mode — recompiles on changes
npm run build  # One-time build
npm test       # Build + automated MCP handler tests
npm start      # Run the server (for testing)

Hardening Path

The current implementation already supports org-scoped API keys with runtime scope enforcement. The remaining hardening step is architectural:

1. Move database access behind a hosted broker or SECURITY DEFINER RPC layer
2. Remove the privileged Supabase server key from end-user machines entirely
3. Keep Q360_API_KEY as the caller credential for org and scope resolution