MCP Server

The ssg CLI ships a built-in MCP (Model Context Protocol) server that exposes SigmaShake governance directly to AI coding agents. Connect it once and your agent evaluates tool calls against your rules, checks health, searches the Hub, or manages Fleet organizations — all through natural conversation.

Transport: stdio (local process, zero network latency)
Protocol: JSON-RPC 2.0 (MCP spec 2024-11-05)
Default tools: 4 core tools (~428 tokens) — opt-in to more as needed

Quick Setup

Step 1 — Install ssg

pnpm add -g @sigmashake/ssg

Step 2 — Connect your AI client

# Auto-configures the MCP server in your client's config:
ssg init --client=claude-code      # Claude Code
ssg init --client=antigravity      # Antigravity / Gemini
ssg init --client=gemini           # Gemini CLI
ssg init --client=codex            # OpenAI Codex

Or add it manually to your MCP config file:

{
  "mcpServers": {
    "ssg-governance": {
      "command": "ssg",
      "args": ["mcp-server"],
      "env": {
        "SSG_CLIENT": "claude-code"
      }
    }
  }
}

For Codex, the equivalent manual config lives in ~/.codex/config.toml:

[mcp_servers.ssg-governance]
command = "ssg"
args = ["mcp-server"]

[mcp_servers.ssg-governance.env]
SSG_CLIENT = "codex"

To include Fleet admin or onboarding tools, add --tools:

{
  "mcpServers": {
    "ssg-governance": {
      "command": "ssg",
      "args": ["mcp-server", "--tools=fleet,onboarding"],
      "env": {
        "SSG_CLIENT": "claude-code"
      }
    }
  }
}

Config file locations:

Client	Config file
Claude Code	`.claude/mcp_config.json` or `~/.claude/mcp_config.json`
Antigravity	`mcp_config.json` or `~/.gemini/mcp_config.json`
Codex	`~/.codex/config.toml`
Cursor	`.cursor/mcp.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`

Step 3 — Restart your client

The MCP server is registered at startup. Restart your AI client once to pick up the new tools.

Step 4 — Say hello

"Set up SigmaShake governance for my project"

Token Budget

MCP servers expose their tool definitions in every conversation — this costs tokens. SSG uses opt-in tool groups so you only pay for what you need.

Mode	Tools	Approx. tokens	Use case
`ssg mcp-server` (default)	4	~428	Daily coding — evaluate, check, status, blocked
`--tools=onboarding`	9	~1,468	Project setup and Hub search
`--tools=fleet`	14	~2,104	Fleet administration
`--tools=all`	19	~3,144	Everything

The startup log tells you exactly what's loaded:

[ssg] MCP server v0.21.1 started (SSG_CLIENT=cursor, tools=core, 4 tools ≈ 428 tokens)

Choosing a tool group

# Default — core governance only (recommended for coding sessions)
ssg mcp-server

# Add onboarding tools (first-time setup, Hub search, rule writing)
ssg mcp-server --tools=onboarding

# Add Fleet admin tools (org creation, SSO, enrollment)
ssg mcp-server --tools=fleet

# Multiple groups
ssg mcp-server --tools=fleet,onboarding

# Everything
ssg mcp-server --tools=all

Or set SSG_MCP_TOOLS in your MCP config's env block instead of passing --tools as an argument:

{
  "mcpServers": {
    "ssg-governance": {
      "command": "ssg",
      "args": ["mcp-server"],
      "env": {
        "SSG_CLIENT": "cursor",
        "SSG_MCP_TOOLS": "onboarding"
      }
    }
  }
}

Per-call overhead is low regardless of mode: a typical ssg_evaluate call (tool name + input) + allow response costs ~62 tokens. The token budget above is the one-time system prompt injection cost.

Tool Reference

The MCP server provides 19 tools across three groups. Only core tools are active by default.

Core Governance (always active)

Tool	Description
`ssg_evaluate`	Evaluate a tool call against active rules. Returns `allow`, `block`, `ask`, `log`, or `force`. Called automatically before every agent tool use.
`ssg_check`	Scan a file or directory path for rule violations.
`ssg_status`	Return governance health: active rule count, daemon status, plan tier.
`ssg_blocked`	Return all blocked or forced tool calls from this session.

Onboarding & Setup (`--tools=onboarding`)

Tool	Description
`ssg_onboard`	Full project setup in one call. Detects your tech stack, initializes `.sigmashake/`, pulls matching Hub rulesets, runs lint, returns a health summary. Start here.
`ssg_doctor`	Comprehensive health check. Returns status for every subsystem: rules loaded, daemon, license tier, client adapter.
`ssg_hub_search`	Search hub.sigmashake.com for rulesets by technology or keyword. Returns IDs, titles, rule counts.
`ssg_hub_pull`	Download and install a Hub ruleset. SHA-256 integrity + Ed25519 signature verified before install.
`ssg_write_rule`	Write a custom `.rules` file to `.sigmashake/rules/`. AI authors the rule from your description; lint runs automatically to validate.

Enterprise Fleet Admin (`--tools=fleet`)

Tool	Description
`ssg_fleet_status`	Local Fleet enrollment status for this machine.
`ssg_fleet_create_org`	Create a new Fleet organization. Returns the `org_id` needed for all subsequent commands.
`ssg_fleet_configure_sso`	Configure OIDC or SAML 2.0 SSO for a Fleet org. Prints required redirect URIs.
`ssg_fleet_set_domain`	Bind an email domain for automatic Enterprise license tier on SSO login.
`ssg_fleet_create_enroll_key`	Generate a reusable enrollment key for developer workstations.
`ssg_fleet_add_member`	Add a user to a Fleet org by email with a specific role.
`ssg_fleet_create_policy`	Create a governance policy (draft state; requires approval to activate).
`ssg_fleet_list_agents`	List enrolled agents with heartbeat status (🟢 online / 🟡 idle / 🔴 offline).
`ssg_fleet_health`	Aggregate org health: agent count, active policies, SSO status.
`ssg_fleet_diagnose_sso`	Diagnose SSO issues: tests OIDC discovery, JWKS validity, prints required redirect URIs.

Tool Examples

`ssg_onboard` — Full project setup

"Set up SigmaShake for my TypeScript + React project"

Response:

SigmaShake Onboarding — /home/user/my-app

Stack Detection
  Detected: TypeScript + React

Initializing .sigmashake/
  ✓ .sigmashake/config.toml
  ✓ .sigmashake/rules/security.rules

Hub Rulesets (2 detected)
  ✓ TypeScript Governance Rules v3
  ✓ React Component Rules v2
  2/2 rulesets installed

Validation
  ✓ All rules pass lint checks

✓ SigmaShake is ready!

`ssg_hub_search` — Discover rulesets

"Find security rules for Docker"

Response:

Hub Search: "docker" — 3 result(s)

  Docker Security Rules
    ID:        rules-docker
    Tech:      docker, containers
    Rules:     8  |  Downloads: 2,341
    Author:    @sigmashake

`ssg_write_rule` — Create a custom rule

"Block any command that runs npm publish without my approval"

Agent writes:

rule require-approval-npm-publish {
  enabled true
  priority 90
  severity error
  ASK execution
  IF command CONTAINS "npm publish"
  MESSAGE "npm publish detected."
  PROMPT "Allow publishing to npm registry?"
}

Response: ✓ Rule file created: .sigmashake/rules/npm-safety.rules | Lint: PASSED

`ssg_evaluate` — Manual rule evaluation

{
  "tool": "run_command",
  "input": { "CommandLine": "git push --force origin main" }
}

Response:

{
  "decision": "block",
  "rule_id": "no-force-push",
  "reason": "Force push is blocked. Use --force-with-lease."
}

Environment Variables

Variable	Description
`SSG_CLIENT`	Client adapter name: `claude-code`, `cursor`, `antigravity`, `gemini`, `codex`, `copilot`, `generic`
`SSG_MCP_TOOLS`	Tool groups to expose: `fleet`, `onboarding`, `all` (comma-separated). Same as `--tools` flag.
`SSG_FLEET_SA_KEY`	Fleet service account key (`ssg_sa_...`) for admin tool authentication
`SSG_FLEET_API_URL`	Override Fleet API base URL (default: `https://fleet.sigmashake.com`)

Governance Enforcement

The MCP server enforces its own governance rules through ssg_evaluate. Every tool call an AI agent makes is evaluated before execution. This applies to all MCP tool calls, not just SigmaShake tools.

The evaluation chain:

Agent calls a tool (e.g. run_command)
ssg_evaluate is called first with the tool name + input
Engine evaluates against active .sigmashake/rules/ files
Decision returned: allow → tool runs, block → tool rejected, ask → paused for approval

Troubleshooting

Tools not appearing in my AI client

Check that ssg mcp-server starts and lists tools:
```
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | ssg mcp-server
```
Should return a JSON array. By default this is 4 tools (core only).

If you need onboarding or fleet tools, they must be explicitly enabled:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | ssg mcp-server --tools=all

Restart your AI client — MCP connections are established at startup.
Verify the config file path and JSON syntax are correct.

"Not authenticated" error from onboarding tools

ssg auth login      # Browser login — one click
ssg auth status     # Verify you're logged in

Fleet tools not available

Fleet tools must be opted-in explicitly:

# Via CLI arg
ssg mcp-server --tools=fleet

# Via mcp_config.json env var
"SSG_MCP_TOOLS": "fleet"

If you call a fleet tool without enabling it, you'll get:

Tool "ssg_fleet_create_org" not enabled. Restart with: ssg mcp-server --tools=fleet

Fleet tools returning permission errors

Use a service account key for Fleet admin operations:

export SSG_FLEET_SA_KEY=ssg_sa_your_key_here

Or ensure your session has org_admin role on the target organization.

`ssg_write_rule` lint errors

The AI will surface the exact lint error. Common causes:

Missing enabled true field
Incorrect indentation (rules use 2-space indent)
Unknown field name in IF condition

See Rule Syntax for the complete language reference.

Security Notes

The MCP server runs locally as a subprocess — no outbound connections except to the Fleet API and hub.sigmashake.com when those tools are used
SSG_FLEET_SA_KEY is read from the process environment — never passed to or exposed by the AI agent
ssg_write_rule writes only inside .sigmashake/rules/ — path traversal is prevented via basename() validation
ssg_fleet_* tools validate fleet_url against *.fleet.sigmashake.com to prevent SSRF
All Fleet API requests include AbortSignal.timeout(10_000) to prevent hanging

Quick Setup​

Step 1 — Install ssg​

Step 2 — Connect your AI client​

Step 3 — Restart your client​

Step 4 — Say hello​

Token Budget​

Choosing a tool group​

Tool Reference​

Core Governance (always active)​

Onboarding & Setup (--tools=onboarding)​

Enterprise Fleet Admin (--tools=fleet)​

Tool Examples​

ssg_onboard — Full project setup​

ssg_hub_search — Discover rulesets​

ssg_write_rule — Create a custom rule​

ssg_evaluate — Manual rule evaluation​

Environment Variables​

Governance Enforcement​

Troubleshooting​

Tools not appearing in my AI client​

"Not authenticated" error from onboarding tools​

Fleet tools not available​

Fleet tools returning permission errors​

ssg_write_rule lint errors​

Security Notes​

Quick Setup

Step 1 — Install ssg

Step 2 — Connect your AI client

Step 3 — Restart your client

Step 4 — Say hello

Token Budget

Choosing a tool group

Tool Reference

Core Governance (always active)

Onboarding & Setup (`--tools=onboarding`)

Enterprise Fleet Admin (`--tools=fleet`)

Tool Examples

`ssg_onboard` — Full project setup

`ssg_hub_search` — Discover rulesets

`ssg_write_rule` — Create a custom rule

`ssg_evaluate` — Manual rule evaluation

Environment Variables

Governance Enforcement

Troubleshooting

Tools not appearing in my AI client

"Not authenticated" error from onboarding tools

Fleet tools not available

Fleet tools returning permission errors

`ssg_write_rule` lint errors

Security Notes