@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.
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.
| Tool | What it returns |
|---|
lookup_regulation(id) | One regulation's structured record: citation, jurisdiction, status, review dates, plain-language summary, and the Controls that may satisfy it. |
search_regulations(query, filters?) | Deterministic keyword + filter search over the corpus, with permanent citation URLs. |
compute_requirements(features, markets, audiences, businessModel?) | Runs the deterministic engine: triggered regulations + Controls, complexity tier, blocker count, per-audience breakdown. Creates or refreshes an idempotent public receipt-report link retained for up to 90 days; use only nonconfidential public or synthetic inputs. |
find_controls(regulationId) | Controls that may satisfy a regulation, each with a priority signal and summary. |
find_vendors(controlId, jurisdiction?) | Vendors and in-house approaches that implement a Control, with effort/cost and a source disclosure. Magist does not accept payment from vendors. |
get_enforcement(regulationId?, since?, limit?) | Recent enforcement actions with penalties, authorities, and primary-source links. |
find_counsel(jurisdiction, practiceArea?, language?) | Open counsel directory by jurisdiction and practice area. Inclusion is not endorsement. |
list_feature_catalog() | The closed feature, market, and audience identifiers accepted by compute_requirements, so agents can validate inputs before analysis. |
verify_ai_answer(token) | Verifies a signed Magist grounding-proof token from the REST API. It proves what Magist served, not legal correctness or applicability. |
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