Schematic MCP Server

[!WARNING] Deprecated. Schematic now hosts an MCP server at https://api.schematichq.com/mcp — see the Schematic MCP documentation to connect. This local stdio server still works but no longer receives new tools or fixes.

An MCP server that connects AI assistants to Schematic -- the platform for managing billing, plans, features, and entitlements.

Use this server to let Claude, Cursor, or any MCP-compatible client look up companies, manage plan entitlements, set overrides, create features, and more -- all through natural language.

Quick Start

Prerequisites

Get your Schematic secret API key: Sign up for a Schematic account and get your secret API key from the Schematic dashboard. Note: use your secret API key, not the publishable key.

Installation

Option 1: Using Claude CLI (Recommended)

Install the package from npm:
Terminal
```
npm i @schematichq/schematic-mcp
```

Add the MCP server to Claude:

Terminal

claude mcp add --transport stdio --scope project schematic --env SCHEMATIC_API_KEY=your-secret-api-key-here -- npx @schematichq/schematic-mcp

Replace your-secret-api-key-here with your actual Schematic API key.

Option 2: Manual Configuration

Claude Desktop / Claude Code

Add to your Claude config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

config.json

{
  "mcpServers": {
    "schematic": {
      "command": "npx",
      "args": ["-y", "@schematichq/schematic-mcp"],
      "env": {
        "SCHEMATIC_API_KEY": "your-secret-api-key-here"
      }
    }
  }
}

Cursor

Add to your Cursor MCP config (Settings > MCP Servers, or edit the file directly):

macOS: ~/.cursor/mcp.json
Linux: ~/.cursor/mcp.json
Windows: %USERPROFILE%\.cursor\mcp.json

config.json

{
  "mcpServers": {
    "schematic": {
      "command": "npx",
      "args": ["-y", "@schematichq/schematic-mcp"],
      "env": {
        "SCHEMATIC_API_KEY": "your-secret-api-key-here"
      }
    }
  }
}

After adding the config, restart Cursor for the server to be picked up.

Configuration

The server needs a Schematic secret API key (not the publishable key). It checks two sources in order:

Environment variable (recommended): SCHEMATIC_API_KEY
Config file (fallback): ~/.schematic-mcp/config.json

config.json

{
  "apiKey": "your-secret-api-key-here"
}

You can find your secret API key in the Schematic dashboard.

Custom API base URL (optional)

By default the server targets the production Schematic API. To point it at a local or non-production API, set SCHEMATIC_API_URL:

config.json

{
  "command": "npx",
  "args": ["@schematichq/schematic-mcp"],
  "env": {
    "SCHEMATIC_API_KEY": "your-secret-api-key-here",
    "SCHEMATIC_API_URL": "http://localhost:8080"
  }
}

When unset, the SDK's production default is used.

Tools

Company Lookup

Tool	Description
`get_company`	Look up a company by ID, name, Stripe customer ID, or custom key. Returns details, plan, trial status, and links.
`create_company`	Create (upsert) a company identified by a key (`keyName`/`keyValue`), with an optional `name` and `traits`. Updates the company if the key already exists.
`get_company_plan`	Get the plan a company is currently on.
`get_company_trial_info`	Check if a company is on a trial and when it ends.
`count_companies_on_plan`	Count how many companies are on a specific plan.
`link_stripe_to_schematic`	Find the Schematic company for a Stripe customer ID, or vice versa.

Company Overrides

Tool	Description
`list_company_overrides`	List overrides by company or by feature.
`set_company_override`	Set or update an override for a company on a specific feature. Supports boolean (`on`/`off`), numeric, and `unlimited` values.
`remove_company_override`	Remove an override so the company falls back to plan entitlements.

Plan Management

Tool	Description
`list_plans`	List all plans.
`create_plan`	Create a new plan.
`add_entitlements_to_plan`	Add feature entitlements to a plan. Auto-detects feature type and sets appropriate value types.

Feature Management

Tool	Description
`list_features`	List all features.
`create_feature`	Create a new feature flag. Supports boolean (on/off), event-based (metered), and trait-based types. Automatically creates an associated flag.

Flag Management

Tool	Description
`list_flags`	List all flags with a targeting summary — for each flag: key, default value, linked feature, and whether it resolves to always-on, always-off, or targeted. Useful for auditing always-on flags (redundant to check in code) or unused flags (candidates for deletion).
`get_flag`	Get full targeting detail for one flag by key: default value, every rule (type, value, priority, condition count), last-checked time, and the always-on / always-off / targeted determination.

Example Prompts

Once configured, try asking your AI assistant:

"What plan is Acme Corp on?"
"List all my plans and their features"
"Create a boolean feature called 'Advanced Analytics'"
"Set an override for Acme Corp to have unlimited API calls"
"How many companies are on the Pro plan?"
"Find the Schematic company linked to Stripe customer cus_abc123"
"List all flags and tell me which ones are always-on"
"Show me the targeting rules for the billing.credits flag"

Development

bash

# Install dependencies
yarn install

# Build
yarn build

# Run in development mode (auto-recompile on changes)
yarn dev

# Run tests
yarn test

License

MIT