@hai-neo/mcp

MCP server that connects coding agents (Claude Code, Codex, OpenCode, …) to your Holistic AI Neo workspace — so you can manage projects, model cards, and AI security scans from inside your editor.

1. Get an API key

1. Sign in to your Holistic AI Neo workspace.
2. Open Settings → API Keys.
3. Create either:
   • a platform key — full access; can list and create projects.
   • a project key — pinned to a single project; cannot create projects but can scope every other tool call to its project automatically.
4. Copy the hai_… value.

2. Wire it up

In your code agent, add this to ~/.claude.json (or a project's .mcp.json):

{
  "mcpServers": {
    "hai-neo": {
      "command": "npx",
      "args": ["-y", "@hai-neo/mcp"],
      "env": {
        "HAI_API_URL": "https://api.neo.holisticai.io",
        "HAI_API_KEY": "hai_..."
      }
    }
  }
}

Restart your code agent. The agent sees describe_api plus one set of tools for each service it has access to.

npx -y runs the latest published version on demand — no install step.

What you can do

| Service | Tools | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | core | describe_api — overview of which services are enabled | | projects | list_projects, create_project (platform keys only) | | model-cards | list_model_cards, get_model_card, create_model_card, update_model_card, delete_model_card | | project-scans | run_project_scan, list_project_scans, get_project_scan | | pentest | create_pentest_scan, list_pentest_scans, get_pentest_scan | | redteam | create_redteam_run, list_redteam_runs, get_redteam_run | | bias | create_bias_run, list_bias_runs, get_bias_run | | compliance | list_compliance_frameworks, create_compliance_audit, list_compliance_audits, get_compliance_audit, get_compliance_audit_summary | | reports | list_reports, get_report, generate_project_report, generate_scan_report, generate_audit_report, generate_bias_report (project keys only) |

Each service also publishes a markdown reference at hai://services/<name> that the agent can pull on demand for detailed docs and the exact request shape — no need to carry it in every tools/list response.

Configuration

| Env var | Required | Example | Notes | | ------------------ | -------- | --------------------------------- | ---------------------------------------------------- | | HAI_API_URL | yes | https://api.neo.holisticai.io | Holistic AI Neo API host. | | HAI_API_KEY | yes | hai_… | Platform or project key. | | HAI_MCP_FEATURES | no | core,model-cards | Comma-separated allow-list. Default: every service. | | HAI_MCP_MODE | no | lazy (or static, the default) | Static = all tools at boot. Lazy = enable on demand. |

Narrowing the tool surface

If a particular connection only needs a subset of services, set HAI_MCP_FEATURES:

"env": {
  "HAI_API_URL": "https://api.neo.holisticai.io",
  "HAI_API_KEY": "hai_...",
  "HAI_MCP_FEATURES": "core,model-cards"
}

Lazy mode

In lazy mode, only describe_api plus a small kernel (list_services, enable_service, disable_service) is exposed at boot. The agent enables a service when it needs it, the MCP fires tools/listChanged, and the new tools appear:

1. describe_api()              → list of services
2. enable_service("pentest")   → pentest tools appear
3. (use them)
4. disable_service("pentest")  → reclaim context for the next turn

Turn it on with:

"env": { ..., "HAI_MCP_MODE": "lazy" }

Verify

Use the official MCP Inspector to list tools and invoke them without leaving the terminal:

HAI_API_URL=https://api.neo.holisticai.io \
HAI_API_KEY=hai_... \
  npx @modelcontextprotocol/inspector npx -y @hai-neo/mcp

Or use the bundled smoke test (assumes you're running from the hai-neo repo with a built dist/):

HAI_API_URL=https://api.neo.holisticai.io HAI_API_KEY=hai_... \
  bash mcp/diagnose.sh

License

MIT.