@trigguard/mcp-server

Production-grade stdio MCP server for TrigGuard authority.

Version: 1.1.0 (backwards-compatible additive release over the 7-tool v1.0 surface)

Transport only — all decisions flow through:

MCP tool → @trigguard/agent-sdk → POST /v1/execute

Decision model: PERMIT · DENY · SILENCE (no ESCALATE wire state for agents — escalation metadata is returned as explanation fields)

Install (npm)

npm install -g @trigguard/mcp-server
export TRIGGUARD_API_KEY=tg_live_…

For application code (non-MCP), use trigguard — npm install trigguard.

Full MCP setup: MCP npm quickstart

Authentication (two rails)

| Rail | Env vars | Tools | |------|----------|-------| | Gateway API key | TRIGGUARD_API_KEY + TRIGGUARD_ORG_ID (or TRIGGUARD_ORGANIZATION_ID) (+ optional TRIGGUARD_GATEWAY_URL) | authorize_action, verify_receipt, explain_decision, get_surface, list_surfaces, health_check | | Session JWT (org / Policy Platform) | TRIGGUARD_SESSION_TOKEN + TRIGGUARD_ORG_ID (+ optional TRIGGUARD_CONTROL_PLANE_URL) | list_org_policies, list_pending_policy_changes, preview_policy_intent |

• API key alone is not enough for org policy tools.
• Session JWT alone is not enough for authorize_action.
• Credentials stay in the MCP server process — never pass them in LLM tool arguments.

Obtain a session via tg login, then export the token / org id (see tg whoami).

Tools

| Tool | Auth rail | Purpose | |------|-----------|---------| | authorize_action | API key | Governed PERMIT / DENY / SILENCE + v1.1 explanation fields | | verify_receipt | API key | Lookup / verify by execution id; optional include_receipt | | explain_decision | API key | Structured “why” for a decision (execution_id and/or authorize_result) | | get_surface | Public registry | One surface’s registry metadata (read-only) | | list_surfaces | Public registry | Discover registered surface ids | | get_policy | Bundled artifact | Human-readable metadata only — not live evaluation | | list_org_policies | Session JWT | List org policies (read-only) | | list_pending_policy_changes | Session JWT | Pending change requests (read-only) | | preview_policy_intent | Session JWT | Compile-only preview — does not persist | | health_check | None / optional key | Gateway reachability + policy engine status |

Not MCP tools (by design): policy create / approve / activate, audit history browse. Use tg policy … or the console.

authorize_action response (v1.1 additive fields)

Existing fields are unchanged. New fields are always present (nullable):

| Field | Meaning | |-------|---------| | reason_code | Public gateway reason code when available | | escalation_required | true when escalation metadata / ESCALATE evidence is present | | escalation_reason | Reason associated with escalation when present | | policy_version | Policy bundle version when available | | evaluation_id | Decision / evaluation id when available (often same as execution_id) |

verify_receipt (v1.1)

| Parameter | Default | Meaning | |-----------|---------|---------| | include_receipt | false | When true, include the receipt document under receipt |

Cursor / Claude configuration

{
  "mcpServers": {
    "trigguard": {
      "command": "trigguard-mcp-server",
      "env": {
        "TRIGGUARD_GATEWAY_URL": "https://api.trigguardai.com",
        "TRIGGUARD_API_KEY": "${env:TRIGGUARD_API_KEY}"
      }
    }
  }
}

For org policy tools, also set TRIGGUARD_SESSION_TOKEN and TRIGGUARD_ORG_ID in the MCP server env.

Environment

| Variable | Purpose | |----------|---------| | TRIGGUARD_GATEWAY_URL | Gateway base URL (default: https://api.trigguardai.com) | | TRIGGUARD_API_KEY | API key (tg_live_…) — required for authorize_action | | TRIGGUARD_ORG_ID / TRIGGUARD_ORGANIZATION_ID | Organisation id for API-key authorize (X-Consumer) and org policy tools | | TRIGGUARD_MCP_ACTOR_ID | Actor id for authorize calls (default: trigguard-mcp-server) | | TRIGGUARD_SURFACE_REGISTRY_PATH | Optional local registry override (dev only) | | TRIGGUARD_POLICY_BUNDLE_PATH | Optional local policy metadata override (dev only) | | TRIGGUARD_SESSION_TOKEN | Control-plane session JWT for org policy tools | | TRIGGUARD_ORG_ID | Active org / workspace id for org policy tools | | TRIGGUARD_CONTROL_PLANE_URL | Control plane base (default: https://control.trigguardai.com) |

Errors

Auth / validation failures return MCP isError: true with a structured body:

{
  "ok": false,
  "error": {
    "code": "session_auth_required",
    "message": "…",
    "remediation": "…"
  }
}

Monorepo development

npm run build -w @trigguard/mcp-server
TRIGGUARD_API_KEY=tg_live_… npm run start -w @trigguard/mcp-server
npm test -w @trigguard/mcp-server

Release notes

See RELEASE_NOTES_v1.1.0.md and MIGRATION_v1.1.0.md.