# Schematic

> Manage companies, plans, features, and billing through SchematicHQ

- **Type:** MCP server
- **Install:** `agentstack add mcp-schematichq-schematic-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [SchematicHQ](https://agentstack.voostack.com/s/schematichq)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.3.4
- **License:** MIT
- **Upstream author:** [SchematicHQ](https://github.com/SchematicHQ)
- **Source:** https://github.com/SchematicHQ/schematic-mcp

## Install

```sh
agentstack add mcp-schematichq-schematic-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Schematic MCP Server

An [MCP](https://modelcontextprotocol.io/) server that connects AI assistants to [Schematic](https://schematichq.com) -- 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

1. **Get your Schematic secret API key**: Sign up for a [Schematic account](https://schematichq.com) and get your **secret** API key from the [Schematic dashboard](https://app.schematichq.com). Note: use your secret API key, not the publishable key.

### Installation

#### Option 1: Using Claude CLI (Recommended)

1. Install the package from npm:
   ```bash
   npm i @schematichq/schematic-mcp
   ```

2. Add the MCP server to Claude:
   ```bash
   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):

```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`

```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:

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

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

You can find your secret API key in the [Schematic dashboard](https://app.schematichq.com).

### 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`:

```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](https://docs.schematichq.com/developer_resources/key_management). Returns details, plan, trial status, and links. |
| `create_company` | Create (upsert) a company identified by a [key](https://docs.schematichq.com/developer_resources/key_management) (`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. |

## 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"

## 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

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [SchematicHQ](https://github.com/SchematicHQ)
- **Source:** [SchematicHQ/schematic-mcp](https://github.com/SchematicHQ/schematic-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.3.4 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.3.4** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-schematichq-schematic-mcp
- Seller: https://agentstack.voostack.com/s/schematichq
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.