MCP Statsig Server

Overview

• Model Context Protocol (MCP) server exposing Statsig Console API tools.
• Local stdio transport for AI tools; optional HTTP coming later.

Quick Start

• Copy .env.example to .env and set STATSIG_CONSOLE_API_KEY (not required for the health_check tool). Optionally set STATSIG_CONSOLE_BASE_URL (defaults to https://api.statsig.com/console/v1).
• Dev: cd agents/mcp-statsig-server && npm run dev
• Build: cd agents/mcp-statsig-server && npm run build
• Run (compiled): cd agents/mcp-statsig-server && npm start

Bring Your Own Key (Universal Use)

• Goal: anyone can use the server without editing client configs. Two options:
  • Env var in client config: set STATSIG_CONSOLE_API_KEY in your MCP client (e.g., Claude Desktop claude_desktop_config.json).
  • In-session BYOK (recommended): call the auth tool to provide your key, optionally persisting it locally.

Auth Tools

• statsig_auth_set_key — Set your Statsig Console API key for this session. Optional persist: "true" stores it in ~/.config/mcp-statsig-server/credentials.json.
  • Example: { "apiKey": "console-xxxxx", "persist": "true" }
• statsig_auth_status — Reports whether a key is set and its source (env|memory|file|none).
• statsig_auth_clear — Clears the in-memory key. Optional removePersisted: "true" deletes the saved file.

How it resolves your key

• Precedence: in-memory (set via statsig_auth_set_key) → STATSIG_CONSOLE_API_KEY env → persisted file.
• On startup, if no env var is present and a persisted key exists, it is loaded automatically.

Security Notes

• The server never logs secrets and routes logs to stderr to protect MCP stdout.
• Persisting to disk writes plaintext under ~/.config/mcp-statsig-server/credentials.json. Prefer in-memory if you do not want disk storage.
• Avoid passing keys in shared transcripts. If your client logs tool arguments, use ephemeral (non-persisted) mode.

MCP Usage

• Configure your MCP-enabled client to launch mcp-statsig-server (stdio). The server reads STATSIG_CONSOLE_API_KEY and handles the required Console API auth header automatically.
• Tools (high level):
  • Health: health_check.
  • Gates: list/get/versions + create/update/delete + lifecycle (enable|disable|launch|archive|unarchive) + load_pulse.
  • Dynamic Configs: list/get + create/update/delete + enable|disable + versions.
  • Experiments: list/get + pulse/cumulative exposures + lifecycle + group enable/disable + restart-as-new.
  • Segments/Tags/Metrics/Events/Users/Teams/Layers: read and mutation coverage per Console API.

Distribute to Others

• Publish to npm (recommended):
  • Bump version: npm version patch (or minor/major)
  • Publish: npm publish --access public (prepublish builds and ships dist/)
• Consumers (Claude Desktop) can reference via npx:
  • Config snippet:
    • "mcp-statsig-server": { "command": "npx", "args": [ "-y", "mcp-statsig-server" ] }
  • Then run statsig_auth_set_key to provide their own key.
• Alternatively, share the built folder:
  • Zip dist/ and this README; recipients run node dist/index.js.
  • Still universal: they set their own key via auth tools.

Smoke Test (read-only)

• From repo root: npx tsx agents/mcp-statsig-server/scripts/full-smoke.ts
• Outputs JSON results under agents/mcp-statsig-server/smoke-results/<timestamp>/.

Project Layout

• src/index.ts — bootstrap, stdio transport, tool registration
• src/config.ts — env parsing and validation (zod)
• src/logger.ts — pino logger
• src/tools/ — tool handlers

Notes

• No nested git repo is created. If/when we extract this to a standalone repo, we can use git subtree split or git filter-repo.
• By default we operate against your development project. There is no additional gating required from you for development use.