@magist/mcp-server

Connect Magist to your AI host over the Model Context Protocol. Magist is an open, deterministic, cited reference for product regulation: which laws apply to a product, the obligations and Controls they imply, and the primary sources behind each. Open data (CC BY-SA 4.0), a deterministic engine (same inputs produce the same outputs, no LLM in the path), permanent citation URLs, and a named-practitioner attribution on every response.

This package is a thin stdio bridge to the hosted server at https://magist.io/api/mcp. Remote-capable hosts can skip it and point straight at that URL.

Offline receipt integrity

The separate receipt-v9 content-integrity utility checks a saved JSON body hash using only Node built-ins. It makes no network call and does not run the engine or authenticate the sender. Its synthetic tests and source are separate from the published bridge and plugin payloads.

Related MCP server: US Regulations MCP Server

Research plugin packages (experimental previews)

This repository also contains the separate magist-research 0.1.1 portable plugin: root plugin.json, the remote connection in mcp.json, and a newly authored workflow in skills/magist-research/. It connects directly to the public HTTPS service and does not run the npm stdio bridge.

The portable connection uses only type and url, as allowed by the Agent Plugins 1.0.0 MCP schema. The endpoint requires no authentication. The schema does not admit the server-level authentication extensions shown in some host-specific examples; those extensions are omitted here. Schema validation alone does not establish that a host can install and run the complete plugin.

Create its bounded source package with Python 3.9 or newer:

python3 scripts/package-plugin.py --output /absolute/new/path/magist-research-0.1.1.zip

The ZIP includes the two portable manifests, the skill and its MCP dependency declaration, an existing public Magist icon, and this repository's MIT license. It excludes the bridge executable, dependencies, private platform source and assets. The plugin version is independent of @magist/mcp-server@0.1.1.

This is a proposed integration package, not an accepted directory listing or a host validation certificate. Public submission uses OpenAI's With MCP route; publisher verification, actual host/reviewer cases, media, any required visual assets, connection checks and submission review remain separate requirements. See the portable package format.

OpenAI listing metadata and five positive/three negative reviewer scenarios are included in plugin.json. Those are proposed host cases, not records of completed installed-plugin runs. A reviewer video is not yet supplied; the website demo is not an installed-plugin walkthrough.

Claude plugin and optional Desktop bundle

The Claude plugin lives at integrations/claude. It uses Claude's separate .claude-plugin/plugin.json and .mcp.json format, pins its reviewed Claude skill bytes, and connects to the same hosted endpoint. Version 0.1.2 adds an explicit audience, bounded research work shape, evidence-confidence bands and escalation rules, retaining the illustrative lookup and response template. These design controls do not establish unconditional framework readiness, installed-host behavior or directory acceptance. The shared OpenAI skill and optional Desktop bundle remain separate, unchanged artifacts. Its clean subfolder excludes this repository's top-level bin/, which chat and Cowork do not accept in a plugin. Build both artifacts without installing dependencies:

python3 scripts/package-claude.py --kind plugin --output /absolute/new/path/magist-claude-plugin-0.1.2.zip
python3 scripts/package-claude.py --kind desktop --output /absolute/new/path/magist-desktop-0.1.1.mcpb

The .mcpb embeds the exact dependency-free published 0.1.1 bridge and requires Node.js 18 or newer. It is unsigned and for private Desktop testing. Claude's current directory no longer accepts Desktop MCPB listings. For public review, submit the remote MCP connector and the integrations/claude plugin folder as two linked submissions from the same intended publisher organization. See Claude's current directory routes. No package here implies installation, portal validation, acceptance or a completed Claude workflow.

Beta: content under attorney review. The server is live and the engine is stable; substantive attorney review of the regulation corpus is in progress. Entries carry a contentReviewStatus field (reviewed is human-verified, draft is AI-prepared and pending review). Magist returns legal information for research and attorney handoff, not legal advice. Consult a licensed attorney before relying on any output for a launch decision.

One-line install

Claude Code (CLI) uses the remote transport directly (no npm install):

claude mcp add --transport http magist https://magist.io/api/mcp

Claude Desktop / Cursor / Windsurf (npx): add the bridge to the host's mcpServers config:

{
  "mcpServers": {
    "magist": {
      "command": "npx",
      "args": ["-y", "@magist/mcp-server"]
    }
  }
}

• Claude Desktop: Settings -> Developer -> Edit Config (claude_desktop_config.json). Restart Claude after saving.

• Cursor: Settings -> MCP -> Add new server, or edit ~/.cursor/mcp.json.

• Windsurf: edit ~/.codeium/windsurf/mcp_config.json, then reload.

• Codex: add to ~/.codex/config.toml:

  [mcp_servers.magist]
  command = "npx"
  args = ["-y", "@magist/mcp-server"]

ChatGPT (Developer Mode / Connectors), Manus, and other remote-capable hosts: add a custom connector pointing at the Streamable-HTTP endpoint https://magist.io/api/mcp (no npm package needed).

Verify it works

A 200 with name: "magist" means the endpoint is live:

curl -s https://magist.io/api/mcp

List the tools (you should see nine):

curl -s -X POST https://magist.io/api/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

In your host, once connected, ask Magist to look up COPPA and list its Controls. A working connection returns a cited regulation record, not a refusal or a no-such-tool error.

Tools

Eight tools read the public corpus or verify a grounding-proof signature. compute_requirements additionally persists the public receipt report described above. Access is unauthenticated and subject to server rate limits; do not send personal, confidential or privileged information. Tool-call telemetry may be recorded. The bridge package license does not license the hosted platform.

Self-hosting

Set MAGIST_MCP_URL to point the bridge at your own deployment of the open corpus and engine:

{
  "mcpServers": {
    "magist": {
      "command": "npx",
      "args": ["-y", "@magist/mcp-server"],
      "env": { "MAGIST_MCP_URL": "https://your-host.example.com/api/mcp" }
    }
  }
}

For host LLM developers

Every tool response is wrapped in a canonical envelope. When you render a Magist response to a user: render the disclaimer.text field verbatim; do not restate outputs as directives or conclusions; surface the practitioner attribution and the verification field; suggest a licensed attorney when counsel_recommended is true; and prefer the citations links when you summarize.

Links

• Docs: https://magist.io/mcp

• Open-data hub: https://magist.io/data

• License (this package): MIT. The corpus is CC BY-SA 4.0.