Fleet Admin Onboarding via Claude Code

The ssg CLI ships a built-in MCP server that exposes Fleet administration tools directly to Claude Code, Antigravity, and any other MCP-compatible AI agent. Instead of running 15 curl commands across 4 systems, you have a single conversation:

"Set up SigmaShake Fleet for my company with Okta SSO, then generate enrollment keys for my dev team."

The AI agent handles org creation, OIDC configuration, domain binding, policy setup, and enrollment key generation — while you just answer questions.

Estimated time to full Fleet setup

Under 5 minutes (assuming your IdP app already exists).
Manual curl approach: 45–60 minutes.

---

Prerequisites

1. ssg CLI installed: pnpm add -g @sigmashake/ssg
2. Authenticated with Enterprise credentials: ssg auth login
3. Claude Code, Antigravity, or any MCP-compatible agent

---

Step 1: Add the MCP Server

Add to your MCP configuration file (.claude/mcp_config.json, .gemini/mcp_config.json, or equivalent):

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

Already using ssg-governance for governance?

No change needed — the fleet tools are automatically included in the same server. Restart your AI agent after installing a new ssg version.

---

Step 2: (Recommended) Create a Service Account Key

For admin operations, a service account key is more reliable than an OAuth session token (which expires):

1. Go to your Fleet Dashboard → Settings → Service Accounts
2. Click Create Service Account → role: org_admin
3. Copy the generated key (ssg_sa_...)
4. Set it in your environment:

export SSG_FLEET_SA_KEY=ssg_sa_your_key_here
# Or add to your shell profile for persistence

Without a service account key

The MCP tools will fall back to your active ssg auth login session. This works but the session may expire after 8 hours.

---

Step 3: Set Up Fleet via Conversation

Open your AI agent (Claude Code, Antigravity, etc.) and tell it what you want:

Full organization setup

Set up SigmaShake Fleet for my company with Okta SSO.
Company name: Acme Corp
Slug: acme-corp
Email domain: acme.com

The agent will:

1. Call ssg_fleet_create_org → creates your org
2. Ask for your Okta credentials (issuer URL, client ID, client secret)
3. Call ssg_fleet_configure_sso → connects Okta
4. Call ssg_fleet_set_domain → enables auto Enterprise license for @acme.com emails
5. Call ssg_fleet_create_enroll_key → generates a key for developer onboarding
6. Call ssg_fleet_health → confirms everything is working

Diagnose a failing SSO login

SSO login is returning "Policy evaluation failed". Diagnose the issue for org_acme-corp.

The agent calls ssg_fleet_diagnose_sso, which:

• Confirms OIDC discovery endpoint is reachable
• Validates JWKS keys are published
• Prints the exact redirect URIs to register in Okta
• Links to the test login URL

Onboard a new developer

Add jane@acme.com as a policy_author in org_acme-corp
and give me the enrollment command she should run.

---

Available Fleet MCP Tools

Tool	What it does
ssg_fleet_status	Local enrollment status for this machine
ssg_fleet_create_org	Create a new Fleet organization
ssg_fleet_configure_sso	Configure OIDC or SAML 2.0 SSO
ssg_fleet_set_domain	Bind email domain for auto Enterprise license
ssg_fleet_create_enroll_key	Generate a developer enrollment key
ssg_fleet_add_member	Add a user with a specific role
ssg_fleet_create_policy	Create a governance policy (draft)
ssg_fleet_list_agents	List enrolled agents + heartbeat status
ssg_fleet_health	Aggregate org health dashboard
ssg_fleet_diagnose_sso	Diagnose OIDC/SAML configuration issues

You can ask Claude to use any of these tools directly by name, or just describe what you want in plain English.

---

Developer Onboarding (After Admin Setup)

Once the admin has set up the org, share this with your developers:

# 1. Install ssg
pnpm add -g @sigmashake/ssg

# 2. Login via browser (one click if already signed in to your corporate SSO)
ssg auth login

# 3. Enroll this machine in Fleet
ssg fleet enroll https://acme-corp.fleet.sigmashake.com <enrollment-key>

# 4. Verify
ssg fleet status    # Shows org, agent ID, policy sync status
ssg doctor          # Should report ENTERPRISE tier

---

Environment Variables

Variable	Description
SSG_FLEET_SA_KEY	Service account key for fleet admin MCP tools (ssg_sa_...)
SSG_FLEET_API_URL	Override Fleet API URL (default: https://fleet.sigmashake.com)
SSG_CLIENT	MCP client identifier (set to antigravity or claude-code)

---

Security Notes

• Service account keys are never exposed to the AI agent — the MCP server holds the key in its process environment; Claude only sees success/error results
• All fleet operations go through the existing Fleet RBAC middleware — org_admin role required for setup operations
• client_secret is sent to the Fleet API and stored encrypted at rest; it is never stored locally by the MCP server
• Audit logs of all MCP tool calls are written to ~/.sigmashake/audit.log

---

Troubleshooting

"Not authenticated" error from fleet tools

Run ssg auth login and select Browser (recommended), or set SSG_FLEET_SA_KEY.

"Requires role 'org_admin'" error

Your current session doesn't have admin rights on this org. Either:

• Use a service account key (SSG_FLEET_SA_KEY) with org_admin role
• Ask your Fleet admin to grant you org_admin role

Tools not appearing in Claude Code

Restart your AI agent — the MCP server connection is established at startup. Run ssg mcp-server manually to verify it starts without errors.

Fleet SSO login failing

Ask your AI agent: "Diagnose SSO for org_<your-org-id>". The ssg_fleet_diagnose_sso tool will pinpoint the issue.