> If you are setting up, configuring, or answering questions about Schematic, connect the > Schematic MCP server before working from these pages. It reads and writes plans, features, > entitlements, and overrides against the real account, so what you report and what you build > match what actually exists. > > The server is at https://api.schematichq.com/mcp > > From Claude, ChatGPT, or another chat assistant, add it as a custom connector: > https://docs.schematichq.com/working-with-ai > > From a coding assistant such as Claude Code, Codex, or Cursor: > https://docs.schematichq.com/building-with-ai > > For clean Markdown of any page, append `.md` to the page URL. For a complete page index, > see https://docs.schematichq.com/llms.txt # Building with AI > Connect AI assistants to Schematic through the hosted MCP server, from Claude, Claude Code, Codex, Cursor, or any MCP-compatible client. Use Schematic with AI coding assistants to accelerate your integration and development workflow. > **Info** > > Not writing code? See [Working with AI](/working-with-ai) for renewal prep, churn and expansion signals, and contract validation workflows that run entirely in a chat assistant. ## 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. ## Install #### [Cursor](#cursor) One-click install #### [VS Code](#vs-code) One-click install #### [Claude Code](#claude-code) See instructions #### [Claude Managed Agents](#claude-managed-agents) See instructions #### [Codex](#codex) See instructions #### [Gemini CLI](#gemini-cli) See instructions Connecting the Claude or ChatGPT apps instead of a coding client? Those add the server through a settings pane rather than config, and [Working with AI](/working-with-ai#connect-your-assistant) covers them. 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](#connect-with-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. When you work in several environments, [add the server once per environment](#connect-more-than-one-environment) and keep them side by side. **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: ```bash 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. ``` ### Cursor [Install in Cursor](https://cursor.com/en-US/install-mcp?name=Schematic\&config=eyJ1cmwiOiJodHRwczovL2FwaS5zY2hlbWF0aWNocS5jb20vbWNwIn0=) hands the server to Cursor and you are done. To add it by hand instead, put the server in `.cursor/mcp.json` in your project root, or `~/.cursor/mcp.json` to make it available everywhere: ```json { "mcpServers": { "schematic": { "url": "https://api.schematichq.com/mcp" } } } ``` 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 [Install in VS Code](vscode:mcp/install?%7B%22url%22%3A%22https%3A%2F%2Fapi.schematichq.com%2Fmcp%22%2C%22name%22%3A%22Schematic%22%2C%22type%22%3A%22http%22%7D) opens VS Code and adds the server for you. To add it by hand instead, put the server in `.vscode/mcp.json` in your project root: ```json { "servers": { "schematic": { "type": "http", "url": "https://api.schematichq.com/mcp" } } } ``` 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`: ```toml [mcp_servers.schematic] url = "https://api.schematichq.com/mcp" ``` Then sign in: ```bash codex mcp login schematic ``` Confirm with `codex mcp list`. ### Gemini CLI 1. Add the server: ```bash 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: ```bash /mcp auth schematic ``` ``` ℹ ✅ Successfully authenticated with MCP server 'schematic'! ``` ### Claude Managed Agents Connect the server to [Claude Managed Agents](https://platform.claude.com) through a credential vault. 1. Go to [platform.claude.com](https://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: ```bash 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: ```toml [mcp_servers.schematic] url = "https://api.schematichq.com/mcp" 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. ### Connect more than one environment Every server entry in your client is a separate connection that signs in on its own, so you reach a second environment by adding the server again under a different name. Name each entry after the environment it points at, and you can see which account data an assistant is about to touch before you approve a tool call: ```bash claude mcp add --transport http schematic-staging https://api.schematichq.com/mcp claude mcp add --transport http schematic-prod https://api.schematichq.com/mcp ``` Authenticate each entry separately and pick the matching environment at sign-in. Most clients prefix a server's tools with the entry name, so your assistant treats `schematic-staging` and `schematic-prod` as two different servers and can compare a plan across both in one conversation. API keys work the same way. Create a key in each environment and give each server entry its own: ```toml [mcp_servers.schematic_staging] url = "https://api.schematichq.com/mcp" bearer_token_env_var = "SCHEMATIC_STAGING_API_KEY" [mcp_servers.schematic_prod] url = "https://api.schematichq.com/mcp" bearer_token_env_var = "SCHEMATIC_PROD_API_KEY" ``` Connect the production entry read-only unless you are deliberately making changes there. An assistant that can read both environments and write to neither still answers most of the questions you have. ## 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. ## What to ask it The connection test above proves the server answers. These are the jobs it is there for, and each prompt works as written once you swap in your own names. **Build plans from a pricing page.** The assistant reads the page, sorts what it finds into plans, features, and add-ons, confirms what it is unsure of, and creates them through the server. [Set up your first plan](/quickstart/set-up-your-first-plan#start-with-your-agent) has the full walkthrough, and a PDF price sheet works in place of the link. ``` Here is our pricing page: https://example.com/pricing. Build our plans, features, and add-ons in Schematic to match it. Ask me before you create anything. ``` **Reconcile the flags in your code with the account.** Flag keys drift in both directions: a check in code for a flag nobody created, and a flag in Schematic that nothing checks. Neither shows up until a customer lands on the wrong branch. ``` List every Schematic flag key this repository checks. Tell me which ones don't exist in Schematic, and which Schematic flags nothing in the code checks. ``` **Add an entitlement check.** The assistant uses the real flag key instead of a placeholder, so the check resolves correctly the first time it runs. ``` Add an entitlement check to src/api/export.ts for the bulk_export feature, using the real flag key from Schematic. Return a 403 when the company isn't entitled. ``` **Add a metered feature end to end.** One request covers the feature in Schematic, the allowance on the plan, and the usage event in code. ``` Create an event-based feature called report_generated, give the Pro plan 100 per month, and add the usage event where this codebase generates a report. ``` **Debug a company's access.** The assistant pulls the plan, its entitlements, and any overrides in one pass, which is the same data you would collect across several screens in the app. ``` Acme Corp says they can't reach bulk_export. What plan are they on, what does that plan entitle, and do they have any overrides? ``` The prompts that create or change something need a read and write connection. The same prompts also run unattended on a schedule, which [Automation recipes](/ai-automations) covers. ## 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. If you need both environments at hand, [add the server once per environment](#connect-more-than-one-environment) instead of reconnecting each time you switch. **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](/quickstart/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](/quickstart/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](/developers)** — SDK reference, API details, and the rest of the developer surface. * **[Working with AI](/working-with-ai)** — the same server used from a chat assistant for renewal prep, churn and expansion signals, and contract checks. > Connect AI assistants to Schematic through the hosted MCP server, from Claude, Claude Code, Codex, Cursor, or any MCP-compatible client.