Tombstone MCP Server

v2.2.0 — Use Tombstone feature-flag management from any MCP-compatible AI coding assistant (Claude Code, Cursor, VS Code Copilot, etc.).

Start with make dev from the repo root, then connect MCP to http://localhost:8081

Setup

1. Build

cd workspace-mcp
npm install
npm run build

2. Configure your AI assistant

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)

{
  "mcpServers": {
    "tombstone": {
      "command": "node",
      "args": ["/absolute/path/to/Tombstone/workspace-mcp/dist/index.js"],
      "env": {
        "TOMBSTONE_API_URL": "http://localhost:8081",
        "TOMBSTONE_TOKEN": "your-api-token-here"
      }
    }
  }
}

Cursor (.cursor/mcp.json in project root or ~/.cursor/mcp.json globally)

{
  "mcpServers": {
    "tombstone": {
      "command": "node",
      "args": ["/absolute/path/to/Tombstone/workspace-mcp/dist/index.js"],
      "env": {
        "TOMBSTONE_API_URL": "http://localhost:8081",
        "TOMBSTONE_TOKEN": "your-api-token-here"
      }
    }
  }
}

Claude Code (.claude/settings.json)

{
  "mcpServers": {
    "tombstone": {
      "command": "node",
      "args": ["/absolute/path/to/Tombstone/workspace-mcp/dist/index.js"],
      "env": {
        "TOMBSTONE_API_URL": "http://localhost:8081",
        "TOMBSTONE_TOKEN": "your-api-token-here"
      }
    }
  }
}

Or use npx after publishing to npm:

{
  "mcpServers": {
    "tombstone": {
      "command": "npx",
      "args": ["-y", "@tombstone/mcp"],
      "env": {
        "TOMBSTONE_API_URL": "http://localhost:8081",
        "TOMBSTONE_TOKEN": "your-api-token-here"
      }
    }
  }
}

Transport

v2.2.0 uses Streamable HTTP (the current MCP standard transport). The endpoint is:

POST /api/mcp/mcp

Legacy SSE transport is not supported. Ensure your MCP client is on a version that supports Streamable HTTP.

Environment Variables

| Variable | Required | Description | |---|---|---| | TOMBSTONE_API_URL | Yes | Base URL of the Tombstone API (e.g. http://localhost:8081) | | TOMBSTONE_TOKEN | Yes | Bearer token for authentication (also accepted as TOMBSTONE_API_TOKEN) |

Available Tools

All 8 tools are available as of v2.2.0. Tools marked v2 were added in v2.0.0.

| Tool | Description | Key Parameters | |---|---|---| | tombstone_get_flag | Fetch flag metadata by key | key (dot-notation) | | tombstone_kill_switch | Emergency disable a flag immediately | key, reason (min 10 chars) | | tombstone_blast_radius | Risk analysis before flipping a flag (returns BLOCKED / HIGH / MEDIUM / LOW) | key, targetState (bool) | | tombstone_list_stale_flags | List cleanup candidates by inactivity window | days (default 30), limit (default 20) | | tombstone_create_flag | Create a new feature flag | key (dot-notation), description | | tombstone_search_flags | v2 — NLP semantic search across all flags (pgvector-powered) | q (free-text query) | | tombstone_generate_cleanup_pr | v2 — Generate a PR spec for dead-code removal via ast-rewriter | key, repo (optional) | | tombstone_openfeature_setup | v2 — Setup instructions for the OpenFeature SDK | language (typescript or python) |

Tool Details

tombstone_get_flag

Returns current state, metadata, owner, rollout percentage, and recent audit entries for a flag.

tombstone_kill_switch

Immediately sets a flag to false and writes an audit log entry. The reason field must be at least 10 characters — enforced to prevent blank emergency actions from appearing in incident timelines.

tombstone_blast_radius

Computes the risk tier before you flip a flag. Returns one of:

• BLOCKED — active circuit breaker or pending incident correlation; flip refused
• HIGH — affects >10% of traffic or has recent rollback history
• MEDIUM — moderate exposure, proceed with caution
• LOW — safe to flip

tombstone_list_stale_flags

Returns flags that have not been evaluated or modified within the configured window. Useful for scheduling cleanup sprints. The days parameter controls the inactivity threshold (default: 30).

tombstone_create_flag

Creates a new flag in the disabled state. Keys must use dot-notation (team.feature.variant). Returns the new flag's full metadata.

tombstone_search_flags (v2)

Uses pgvector semantic embeddings (generated by the intelligence service) to find flags matching a natural-language query. More useful than a key prefix search when you don't know the exact flag name — e.g. "all payment-related flags that were disabled last month".

tombstone_generate_cleanup_pr (v2)

Given a tombstoned or stale flag key, generates a structured PR spec describing every code site that references the flag and the AST rewrites needed to remove the dead branch. Uses the ast-rewriter engine in the intelligence service. Returns a spec you can pipe into your PR workflow or hand to a code agent.

tombstone_openfeature_setup (v2)

Returns step-by-step setup instructions for wiring the Tombstone gateway into an OpenFeature provider. Pass language: "typescript" or language: "python" to get language-specific code snippets.

Usage Examples

Ask your AI assistant:

• "Get the current state of the payments.checkout.v2 flag"
• "Kill switch auth.legacy-login — reason: CVE-2024-1234 mitigation required"
• "What is the blast radius of enabling billing.new-invoices.enabled?"
• "List all stale flags untouched for more than 60 days"
• "Create a flag search.semantic.v1 owned by the search team"
• "Search for all payment-related flags that were recently disabled"
• "Generate a cleanup PR spec for the tombstoned payments.old-checkout flag"
• "Show me how to set up OpenFeature with Tombstone in TypeScript"

Changelog

v2.2.0

• Version aligned with Tombstone backend v2.2.0 / Dashboard v1.0.0 (self-hosted)
• Local-first setup: connect to http://localhost:8081 via make dev

v2.0.1

• Fix: Streamable HTTP transport endpoint path corrected to /api/mcp/mcp
• Fix: TOMBSTONE_API_URL default updated to port 8081 (flag-api)

v2.0.0

• Added tombstone_search_flags — pgvector-powered NLP semantic search
• Added tombstone_generate_cleanup_pr — ast-rewriter-based dead-code PR spec generation
• Added tombstone_openfeature_setup — OpenFeature provider setup for TypeScript and Python
• Migrated transport from legacy SSE to Streamable HTTP (/api/mcp/mcp)

v1.0.0

• Initial release: tombstone_get_flag, tombstone_kill_switch, tombstone_blast_radius, tombstone_list_stale_flags, tombstone_create_flag, tombstone_search_flags