SaferAgenticAI MCP Server

Serves the SaferAgenticAI framework (canonical criteria + Implementation Patterns layer) to coding assistants via the Model Context Protocol.

Available in

Published to the canonical MCP catalogues — install from a registry-aware client or the CLI below:

• PyPI — saferagenticai-mcp
• Official MCP Registry — io.github.NellInc/saferagenticai-mcp

Also rolling out across the wider MCP ecosystem: mcp.directory, mcpservers.org, PulseMCP (via the registry ingest), and mcp.so.

Install

Pick the path that matches your setup.

Option 1 — uvx (fastest, no manual venv)

If you have uv installed, point your MCP client at:

uvx --from git+https://github.com/NellInc/saferagenticai-mcp saferagenticai-mcp

uv handles isolation and caches the install, so the client can start the server with a single command (see Configure below).

Option 2 — pipx (isolated global install)

pipx install "git+https://github.com/NellInc/saferagenticai-mcp"

Exposes saferagenticai-mcp globally; updated with pipx upgrade saferagenticai-mcp.

Option 3 — manual venv (works offline from a checkout)

Homebrew / system Python blocks direct pip install under PEP 668, so if you've cloned the repo and want an editable install:

python3 -m venv research/mcp/.venv
research/mcp/.venv/bin/pip install -e research/mcp/server

Produces research/mcp/.venv/bin/saferagenticai-mcp. Pattern YAML edits in the repo are picked up live (editable mode).

Option 4 — from PyPI

pipx install saferagenticai-mcp
# or, with the modern uv toolchain:
uv tool install saferagenticai-mcp
# or plain pip:
pip install --user saferagenticai-mcp

For audit-trail reproducibility, pin the version: pipx install saferagenticai-mcp==0.4.1. The package bundles criteria-v1.json + 239 pattern YAMLs + 4 exemplars

• operational_heuristics.yaml inside saferagenticai_mcp/_data/, so a wheel install works without any repo checkout. (The 0.3.0 wheel predates the corpus extension and bundles only 214 patterns, no heuristics; 0.3.1 is the first complete build.)

Configure (Claude Code)

Use the Claude Code CLI. Tested with Claude Code 2.1.318 on 2026-11-05 against 0.4.1 installed with pipx:

claude mcp add --scope user saferagenticai -- saferagenticai-mcp
# Added stdio MCP server saferagenticai with command: saferagenticai-mcp  to user config
# File modified: /Users/you/.claude.json

claude mcp list
# saferagenticai: saferagenticai-mcp  - ✔ Connected

Other install routes use the same form:

claude mcp add --scope user saferagenticai -- uvx saferagenticai-mcp==0.4.1
claude mcp add --scope user saferagenticai -- /absolute/path/to/research/mcp/.venv/bin/saferagenticai-mcp
claude mcp add --transport http --scope user saferagenticai https://mcp.saferagenticai.org/mcp

Scopes: local (the default; this project only) and user (all your projects) are stored in ~/.claude.json; project is stored in .mcp.json at the project root and shows ⏸ Pending approval in claude mcp list until approved in an interactive claude session. A project .mcp.json written by claude mcp add --scope project saferagenticai -- uvx saferagenticai-mcp==0.4.1:

{
  "mcpServers": {
    "saferagenticai": {
      "type": "stdio",
      "command": "uvx",
      "args": ["saferagenticai-mcp==0.4.1"],
      "env": {}
    }
  }
}

Cursor reads the same mcpServers body from ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).

Tools (10 total)

Data sources

• Normative framework: framework/catalog/, loaded through the generated assessor/src/data/criteria-v1.json projection
• Pattern layer: research/mcp/suites/<SUITE>/<pattern_id>.yaml (239 files)
• Exemplars: research/mcp/exemplars/*.yaml (fallback for four anchor subgoals)
• Operational heuristics: research/mcp/operational_heuristics.yaml (15 heuristics)

At startup the server loads both and builds an in-memory index keyed by pattern_id. display_id lookups are also supported but may resolve to multiple subgoals (underlined variants).

Smoke test (without an MCP client)

The 0.4.1 executable has no version or health-check flag, and pipx installs it into its own virtual environment, so a plain python3 cannot import it. Use the environment the package lives in:

pipx runpip saferagenticai-mcp show saferagenticai-mcp   # Version: 0.4.1

"$(pipx environment --value PIPX_LOCAL_VENVS)/saferagenticai-mcp/bin/python" -c "
from saferagenticai_mcp.framework_loader import load_framework
idx = load_framework()
print(f'{len(idx.subgoals)} subgoals, {sum(1 for s in idx.subgoals.values() if s.has_pattern)} with patterns')
"
# 239 subgoals, 239 with patterns

# with uv instead of pipx:
uvx --from saferagenticai-mcp==0.4.1 python -c "import saferagenticai_mcp; print(saferagenticai_mcp.__version__)"

Versioning

• Canonical framework: follows criteria-v1.json's version field.
• Pattern layer: v1-draft.
• Published package: 0.4.1 (framework 1.3-draft, full 239-pattern corpus and 15 operational heuristics bundled, ten tools). Pin explicitly for audit reproducibility.
• 0.4.1 exits cleanly when a stdio client disconnects after a malformed message, keys subgoals by their permanent pattern ids, and bundles the 239-pattern catalog (including D2.10) and 15 operational heuristics.
• 0.4.0 removes the list_unreviewed and review_stats tools and the needs_human_review and reviewed_by pattern fields. It keeps the payload-free executable diagnostics added in the private 0.3.7 origin build. The hosted origin's current release and rollback target are recorded in ../plugin-review/DEPLOYMENT.md.

What's already built in

• Hot reload — server stat-walks the source tree on each tool call; edits show up without restart.
• Load-time validation — required fields, content_type enum, confidence enum. Invalid patterns log WARNINGs but don't fail the server.
• find_patterns_for_task — natural-language task → top patterns grouped by suite. Replaces the need for a separate embedding index at current scale.
• Reverse xref index — built at load, queried by get_reverse_references.

Transport

The default transport is stdio. Streamable HTTP is available with the [http] extra and MCP_TRANSPORT=http. It binds to loopback by default and expects an external HTTPS reverse proxy. The public endpoint is https://mcp.saferagenticai.org/mcp; its deployment and catalog must be verified separately from a local installation.

Not implemented

• Server-side authentication for the public read-only tools.
• Embedding-based semantic search — the field-weighted keyword scoring is sufficient at 239 patterns; embeddings would be worth it at 10× this scale.

The broader agent-native architecture proposes composite orientation, context-pack, workspace, planning, action, and verification operations. They are explicitly not part of the current 0.4.1 interface. See ../../architecture/README.md for the target and compatibility plan.

The authoritative catalog maps current MCP identifiers and slugs to permanent requirement IDs. Server 0.4.1 exposes ten tools, loads the generated packaged snapshot, validates saai.catalog.v1, and reports the shared snapshot hash.

License

This server (the code in this directory) is licensed MIT — see LICENSE.

The safety-framework content it serves (the patterns, canonical criteria, and operational heuristics bundled under saferagenticai_mcp/_data/) is part of the SaferAgenticAI framework, published under CC-BY-4.0 (LICENSE-CONTENT at the repository root; LICENSING.md there sets out what each licence covers). Attribution: Nell Watson and the Agentic AI Safety Community of Practice.