Building with AI

Use Schematic with AI coding assistants to accelerate your integration and development workflow.

Model Context Protocol (MCP)

Schematic hosts an MCP server at https://api.schematichq.com/mcp. Any MCP-compatible AI assistant can connect to it to interact with your Schematic account directly:

• Query company information and plans
• Check feature usage and entitlements
• Manage company overrides
• Create and update features and plans
• Analyze usage patterns

The server speaks streamable HTTP and supports MCP OAuth, which is what most clients need to know to connect.

Common use cases

The MCP integration is particularly useful for code generation, where the assistant queries your actual Schematic data so the integration code it writes matches your real feature keys and plans. It also helps with troubleshooting a specific company, plan, or feature without leaving your editor, analyzing usage patterns through natural language queries, and managing plans by describing the change you want rather than clicking through the app.

Install

OAuth is the better default for every client that supports it. The connection runs as your Schematic user, so it respects your team member permissions and picks up permission changes immediately, and there is no API key to store or rotate. Clients that cannot run the OAuth flow use an API key instead.

Sign-in asks you two things, and both are fixed for the life of the connection. To change either, disconnect the server and connect again.

Which environment. Each Schematic environment carries its own companies, plans, and features, so connecting to the wrong one gives you an assistant that reports an empty account.

Read-only, or read and write. Read-only is the right default. A write connection can never do more than you can do in the Schematic app yourself.

Claude Code

1. Add the server:

$
claude mcp add --transport http schematic https://api.schematichq.com/mcp

2. Start Claude Code and list the servers with /mcp. Schematic is listed as needing authentication:

❯ schematic · △ needs authentication

Select it, press Enter, and follow the browser flow to sign in and choose your environment and access level.

3. Run /mcp again to confirm:

❯ /mcp
  ⎿  Authentication successful. Connected to schematic.

Claude

Open Customize > Connectors, select Add custom connector, and enter https://api.schematichq.com/mcp. Claude runs the same sign-in, environment, and access-level choices in the browser, and the connector then stays available in every conversation without any config file to maintain.

Every Claude plan can add a custom connector, including Free and Pro.

Cursor

Use the one-click install above, or add the server to .cursor/mcp.json in your project root, or ~/.cursor/mcp.json to make it available everywhere:

1
{
2
  "mcpServers": {
3
    "schematic": {
4
      "url": "https://api.schematichq.com/mcp"
5
    }
6
  }
7
}

Cursor prompts you to sign in the first time it connects. Confirm the result under Settings > MCP, where a connected server shows green alongside the number of tools it loaded.

VS Code

Use the one-click install above, or add the server to .vscode/mcp.json in your project root:

1
{
2
  "servers": {
3
    "schematic": {
4
      "type": "http",
5
      "url": "https://api.schematichq.com/mcp"
6
    }
7
  }
8
}

VS Code prompts you to sign in the first time it connects. Run the MCP: List Servers command to confirm the server is running.

Codex

Codex has no CLI shortcut for HTTP servers, so add the server to ~/.codex/config.toml:

1
[mcp_servers.schematic]
2
url = "https://api.schematichq.com/mcp"

Then sign in:

$
codex mcp login schematic

Confirm with codex mcp list.

Gemini CLI

1. Add the server:

$
gemini mcp add --transport http schematic https://api.schematichq.com/mcp

2. Start Gemini CLI and list the servers with /mcp list. Schematic is listed as disconnected:

🔴 schematic - Disconnected (OAuth not authenticated)

3. Authenticate the server:

$
/mcp auth schematic

ℹ ✅ Successfully authenticated with MCP server 'schematic'!

Claude Managed Agents

Connect the server to Claude Managed Agents through a credential vault.

1. Go to platform.claude.com.
2. Open Credential vaults, then Create vault, then Add credential.
3. Select MCP OAuth.
4. Enter the server URL https://api.schematichq.com/mcp.
5. Leave Access token and OAuth client credentials blank.
6. Select Connect and complete the Schematic sign-in when prompted.

Other clients

Point the client at https://api.schematichq.com/mcp over streamable HTTP and let it run the OAuth flow. Clients that only support SSE, or that cannot reach the public internet, need the API key method below instead.

Connect with an API key

Clients that do not support MCP OAuth can authenticate with a Schematic secret API key as a bearer token:

$
claude mcp add --transport http schematic https://api.schematichq.com/mcp \
>
  --header "Authorization: Bearer your-secret-api-key"

In Codex, reference an environment variable rather than pasting the key into your config:

1
[mcp_servers.schematic]
2
url = "https://api.schematichq.com/mcp"
3
bearer_token_env_var = "SCHEMATIC_API_KEY"

Read-only API keys can use only the read tools, which makes them a reasonable choice when you want an assistant that can look but not touch.

Check the connection

Once your client lists Schematic as connected, ask it something you already know the answer to. A real answer confirms both the connection and the environment you picked at sign-in.

• “What plan is company Acme Corp on?”
• “Show me feature usage for the ‘api_calls’ feature across all companies”
• “Create a company override to enable ‘beta_features’ for company comp_123”

The third one needs a read and write connection. If it fails, see the troubleshooting below.

Troubleshooting

The assistant returns no companies, or the wrong ones. Your connection points at a different environment than the one you have open in the app. Each Schematic environment carries its own companies, plans, and features, so a connection to sandbox looks empty next to production data. Disconnect the server in your client, reconnect, and pick the environment deliberately at sign-in.

A write tool returns a permission error. Either you connected read-only, or your role in Schematic doesn’t have write access. Reconnect and choose read and write. If that doesn’t fix it, ask an admin to update your role.

Your client never finishes the OAuth flow. Clients that speak only SSE, and clients running somewhere without outbound internet access, cannot complete the browser handoff. Authenticate with a secret API key as a bearer token instead, using the setup above.

Tools you expect are missing. Most clients cache the tool list from the moment they connect, so a server that gained tools since then still looks the way it did on day one. Restart the client, or remove and re-add the server, and the current list loads.

Best practices

Prefer OAuth over API keys so the connection runs as you and respects your permissions. If you do use an API key, store it securely and never commit it.

Connect read-only unless you specifically need write access, pick the environment deliberately, and verify that query results look right before acting on them in production. Review the code your assistant generates the same way you would review a teammate’s.

Next steps

Your assistant can now read your real feature keys, plans, and entitlements as it writes code, so the integration it produces matches your account instead of a generic example. Pick up the integration where you left it:

• Instrument your app — install an SDK, identify companies and users, report the usage you bill on, and check an entitlement before a feature runs.
• Set up your first plan — start here instead if your account has no plans yet, since the assistant has nothing to read until it does.
• Developer resources — SDK reference, API details, and the rest of the developer surface.
• Working with AI — the same server used from a chat assistant for renewal prep, churn and expansion signals, and contract checks.