Meridian MCP
Implementa, revierte, consulta registros, gestiona planes de facturación y depura webhooks de aplicaciones de Shopify alojadas en Meridian desde tu agente de programación.
Servidor MCP alojado
npx add-mcp 'https://mcp.the-meridian.ai/mcp'Se instala en Claude Code, Codex, Cursor y más
Documentación
Agent Instructions
These are the public docs of Meridian for Shopify apps: hosting, billing (Plan Builder and the @the-meridian/sdk package), CRM, emails and automations for Shopify app developers. Start with these pages: Meridian MCP (https://help.the-meridian.ai/mcp-server.md) to connect a coding agent, AI coding agents (https://help.the-meridian.ai/ai-agents.md) for the agent skill, SDK quickstart (https://help.the-meridian.ai/sdk-quickstart.md), Running your app with the CLI (https://help.the-meridian.ai/cli-dev.md), Deployment (https://help.the-meridian.ai/deployment.md), and Errors (https://help.the-meridian.ai/errors.md) to look up an error code or message. Fetch one page at a time as Markdown (the page URL followed by .md), using the index in https://help.the-meridian.ai/llms.txt. llms-full.txt holds every page in one file of about 900 KB, so avoid loading it whole. With Meridian MCP connected, search these docs with docs_search and docs_get, and read live facts (feature and event keys, plan ids, environments, deployments, logs) from the MCP tools instead of guessing them.
Meridian MCP server for Claude Code, Cursor, Codex
Connect Cursor, Claude Code, Codex or Claude Desktop to Meridian MCP at mcp.the-meridian.ai: OAuth setup, scoping, the full tool catalog and troubleshooting.
Meridian MCP connects the AI coding client you already work in (Cursor, Claude Code, Codex, or Claude Desktop) to your Meridian organizations and apps. Instead of guessing, the agent reads your app's real Plan Builder catalog, deploy plane, runtime logs, secret metadata, Shopify API alerts, Grow config (emails, automations, segments, discounts), and developer databases before it writes a line of code.
So the agent reads your actual feature and event keys before writing isEnabled() / track() calls, reads the real error off a failed deployment before proposing a fix, and can trigger a deploy or roll one back without you leaving the editor.
| Server URL | https://mcp.the-meridian.ai/mcp |
| Transport | Streamable HTTP |
| Authentication | OAuth 2.1 authorization code + PKCE, with dynamic client registration |
| Authorization | Your existing organization role and permissions, re-checked on every call |
| Server version | 1.21.0 |
| Where to set it up | The Meridian MCP page (/mcp) in the dashboard |
Meridian MCP never grants access you don't already have in the dashboard. Every tool call resolves the signed-in user and runs the same permission checks the web app runs, on the same catalog: a tool that mirrors a dashboard action needs the permission that action needs, and a role's app scope applies to every app-scoped tool.
This server accesses the production Meridian platform only, including the staging and development environments of its apps. Apps created on the separate Meridian staging platform are not available through this server. See Environments.
Connect an AI client
Server URL: https://mcp.the-meridian.ai/mcp. There is no API key and no token to paste anywhere: your client registers itself over OAuth and you approve it once in a browser.
[tab] Claude Code
claude mcp add --transport http meridian https://mcp.the-meridian.ai/mcpThen run
/mcpin Claude Code, pick meridian and approve in the browser.To share the server with everyone on the project, commit a
.mcp.jsonat the repository root instead. Thetypeis required for Claude Code. Claude Code asks each person to approve a project server the first time it starts in the project, then/mcpconnects it.{ "mcpServers": { "meridian": { "type": "http", "url": "https://mcp.the-meridian.ai/mcp" } } }The Claude Code plugin bundles the server with the agent skill:
/plugin marketplace add the-meridian-ai/skill, then/plugin install meridian@meridian.
[tab] Cursor
Add the server to
.cursor/mcp.json(this project) or~/.cursor/mcp.json(every project):{ "mcpServers": { "meridian": { "url": "https://mcp.the-meridian.ai/mcp" } } }Then open Customize in the sidebar (Settings → Tools & MCP before Cursor 3) and press Connect next to meridian to approve in the browser.
[tab] Codex
Add the server to
.codex/config.toml(in a trusted project) or~/.codex/config.toml:[mcp_servers.meridian] url = "https://mcp.the-meridian.ai/mcp"Then run
codex mcp login meridianto approve in the browser.
[tab] Claude Desktop
Settings → Connectors → Add custom connector, paste the server URL, then approve in the browser.
Check the connection with the whoami tool: it returns you and every organization you belong to. Then apps_list gives the app_id every other tool takes. See How tools are scoped.
meridian skills install, run from your app's root, writes this config for Claude Code, Codex and Cursor in one go, together with the Meridian agent skill. See AI coding agents.
What happens when you connect
- Your client reads the server URL and discovers Meridian's OAuth endpoints, then registers itself. Nothing has to be pre-created in the dashboard.
- The client opens Meridian's consent screen in a browser. It names the client, what it asks for, and where the access goes: an application on your computer, or a remote server, which the screen names and warns you about. If you are signed out of the dashboard, or your session has expired, Meridian asks you to sign in first and then takes you straight to the consent screen. You don't need to start the connection again from your client.
- On Approve, the client exchanges the authorization code for its tokens. On Deny, nothing is granted.
- The client appears under Connected AI clients on the Meridian MCP page (
/mcpin the dashboard), with when it connected and when it was last used.
Revoke a client
Connected AI clients lists every client you've approved. Revoking one invalidates its access token and refresh token immediately. The client stops working and has to connect and be approved again. Revoked entries stay in the list, marked as revoked, rather than disappearing. Connections are per developer, not per organization.
How tools are scoped
The server keeps no state between calls. There's no "current app" or "current organization", so every app-scoped tool takes explicit identifiers:
| Argument | Required | What it is |
|---|---|---|
app_id | On app-scoped tools | The app's public identifier, as returned by apps_list. |
organization_id | Optional | An organization uuid or slug. When supplied, app_id is resolved within it and may be a slug too. |
The opening move for an agent is whoami, then apps_list. The identifiers every other tool needs come from those two calls. Output always uses the same public identifiers the platform API exposes; internal numeric ids never appear.
Tool catalog
Sixty-six tools. Each declares all four MCP behaviour hints (read-only, destructive, idempotent, open world) so a well-behaved client knows what it can run unattended: read-only (no side effects, safe to repeat), idempotent (repeating the same call changes nothing more), destructive (needs confirmation), or write (creates or updates Meridian config, draft-only for emails and automations). A write that is not marked idempotent creates something new on every call. The catalog leans towards facts your repository can't tell you: the variables injected into the deployed runtime, the live database schema, where webhooks are routed, and the Grow config an agent needs when wiring lifecycle flows.
Orientation
| Tool | Annotation | Purpose |
|---|---|---|
whoami | read-only | The calling user plus every organization they belong to, with role and key permissions. No arguments. |
apps_list | read-only | Apps visible to the user, each with the app_id every other tool needs. |
app_get | read-only | One app's detail: Shopify connection state, environments, plan feature entitlements. The shopify block gives connection_status, connection_error and connection_error_reason, why the last Partner connection failed (partner_token_rejected, stored_token_rejected, partner_organization_not_found, shopify_app_not_found, partner_api_unreachable, partner_auth_failed, or null). Each environment carries the same addresses, domains and database as environments_list, without the scaling config. auto_deploy is the same block as in environments_list: what a push deploys, and to which environment. The environments and auto_deploy fields are omitted without Hosting: View on the app, and the entitlements without Plan builder: View. |
docs_search | read-only | Ranked passages from Meridian's public product docs (the same knowledge base Answers uses). Returns path, title, URL, heading, anchor, snippet, and score. No app_id. |
docs_get | read-only | One public docs page in full by relative path (for example mcp-server.mdx). Same tree as meridian://docs/{path}. |
Plan Builder
The highest-value surface: what an agent reads before writing SDK integration code, and, since 1.13.0, what it uses to set up an app's plans and features without the dashboard.
| Tool | Annotation | Purpose |
|---|---|---|
plans_list | read-only | The app's plans (handle, status, monthly/yearly price, trial days) and the feature and event terms each grants. |
features_list | read-only | The feature catalog: each feature's key (what isEnabled("<key>") gates on), type (boolean/number), and per-plan value. |
events_list | read-only | The metered-usage event catalog: each event's key (what track({ eventKey }) reports against), unit, and per-plan terms. |
events_create | write | Adds a metered-usage event to the catalog: name, key (lowercase snake_case, unique per app across events and usage views, immutable), optional unit, description, and default metering terms. Per-plan terms are set on the plan with plan_create or plan_update. |
feature_create | write | Adds a feature to the catalog: name, key (what isEnabled("<key>") checks, lowercase snake_case, unique per app, immutable), type (boolean or number, immutable), optional description. The feature is in no plan until a plan grants it. |
feature_update | write, idempotent | Renames a feature or edits its description. Its key and type never change. |
plan_create | write | Creates a plan as a draft: name, price_monthly (0 for a free plan), optional description, price_yearly, trial_days, the features it grants and its per-event usage events terms. Each features item is { feature_id, value }: feature_id is the id from features_list or feature_create (not the feature's key), and value is the limit of a number feature (leave it out for a boolean feature, or for no limit). Each events item needs event_id (from events_list), included_quantity, overage_rate, overage_unit and capped_amount. Merchants don't see the plan until it is activated. |
plan_update | write, idempotent | Edits the plan named by plan_id (the id or the handle from plans_list): only the fields sent change. features and events take the same items as plan_create, and each replaces the plan's whole list. Never changes its status. |
plan_activate | write, idempotent | Puts the draft named by plan_id live, so merchants can subscribe to it. Requires confirm: true in the same call. |
plan_deactivate | write, idempotent | Takes the active plan named by plan_id off the pricing page (back to draft). Stores already subscribed keep it. |
entitlements_explain | read-only | What one shop is entitled to right now, resolved through the same path the SDK reads. A debugging aid for a gate behaving unexpectedly. |
The write tools follow the same rules as the Plan Builder in the dashboard, and need Plan builder: Edit on the app:
- A plan name is unique among the app's plans, and a plan's shape is checked as on the dashboard: a yearly price needs a monthly one, and at most one event charges for usage, on a plan without a yearly price.
- A plan with live subscribers refuses a change that would cost them more (
PLAN_LOCKED). Save it as a new version from the dashboard: they stay on the version they approved. - Only the current version of a plan can be activated, and an older version keeps its name.
- Activating any plan needs the app's session store, as in the dashboard. See Publishing plans.
- A paid plan (a price, or an event with an overage rate) can only go live once the app can charge through Shopify:
plan_activate, and aplan_updatethat prices an active free plan, are refused withSHOPIFY_BILLING_NOT_READYand what is missing (the Shopify client ID or secret in Settings > Meridian SDK, the Partner connection in Settings > Integrations). See Paid plans need Shopify billing set up. plan_activatewithoutconfirm: truechanges nothing and says what activating would do. Have your agent ask you before it passesconfirm: true. A plan that is already active is returned unchanged.plan_deactivateundoes it, without confirmation: nobody is charged by it.- Changes to an active plan reach new merchants at once, as a save in the dashboard does.
Deploy
| Tool | Annotation | Purpose |
|---|---|---|
environments_list | read-only | Environments with type, region, base URL, public URL, domains, release_command, health check path, scaling config with always_on (true when the environment keeps an instance warm), database, and config_pending_deploy (true when settings changed that only reach the app with the next deploy) with config_changed_at. Next to the list, auto_deploy says what a push to the connected repository deploys: enabled, branch, target, and where the push really lands, environment_type with its environment_id. |
environment_create | idempotent | Add a development or staging environment, like Add environment in the dashboard, within the plan's environment allowance and in the app's region. Optional starting settings: release_command, healthcheck_path, cpu, memory, max_instances, concurrency, timeout_seconds, name. An app that already has an environment of that type gets it back unchanged (created: false). Never production: that environment is created with the app. Needs Hosting: Edit. |
environment_update | destructive | Change one environment's settings: release_command, healthcheck_path, container_port, cpu, memory, max_instances, concurrency, timeout_seconds, name. Send only what changes; null clears a setting. Compute values are limited by the plan. The production environment needs confirm: true. Returns changed and the environment. Needs Hosting: Edit. |
sdk_credentials_set | destructive | Save the app's Shopify client ID, client secret or both, like the Shopify API credentials card under App settings > Meridian SDK. They reach every environment at its next deploy, production included, so the call needs confirm: true. A credential can be replaced, not cleared. The secret is never returned. Needs Applications: Edit. |
app_readiness_get | read-only | Whether the app is ready to deploy: each readiness check with key, status (pass, warn, fail), code (such as missing_shopify_client_secret), message and fix (where in the dashboard, with its URL). A fail makes the deploy fail before its build, except shopify_billing, which the deploy logs as a warning. Takes an optional environment_id (default: production). Needs Hosting: View. |
managed_variables_list | read-only | The variables Meridian injects at deploy time (SHOPIFY_API_KEY, SHOPIFY_APP_URL, SCOPES, the MERIDIAN_* and managed DB_* set). Names and metadata only, never values. source says where each comes from (sdk_credentials, platform, database, or shopify_app_config for SCOPES, whose source_file names the shopify.app.toml it is read from). For a variable one of yours overrides, override_value says whether the two values are same, different or unknown (only the Shopify pair and NODE_ENV are compared). |
github_refs_list | read-only | Branches and recent commits of the connected GitHub repository. |
deployments_list | read-only | Recent deployments with status, current step, build step (built, reused image, or none for a rollback), timing, git ref/sha, and who triggered them. A failed one carries error_code and error_message (see Why a deploy fails), and error_message_pending: true while that reason may still be replaced by the container's output or the stored build log. |
deployment_get | read-only | One deployment's detail: finished, steps (queued, build, deploy, verify, each with status, timing, duration and detail), and its log lines. Its build_logs_url and runtime_logs_url open only for Meridian staff: read a failure from error_message and the log lines, and runtime output with logs_tail. wait_until: "finished" waits up to 50 seconds for the deployment to finish before answering, so an agent follows a deploy without a sleep loop. Lines come newest first (order: "asc" for oldest first), limit keeps the latest (default 100), and build boilerplate is left out unless include_noise: true. See Following a deployment. |
logs_tail | read-only | Recent runtime logs for one environment, when the app's plan includes logs. Options include since/until, deployment_id, min_severity (a floor, so WARNING also matches errors), contains, and source (web by default, worker for the Worker add-on, all, or release for the output of the environment's release command). Every answer carries server_time and the window queried, in UTC. |
scheduler_jobs_list | read-only | The Scheduler jobs of one environment: each job's type (short or long), path or command, schedule, paused state, next runs, last run and run in progress, with the fixed limits of each type and the app's long-task hours for the month. enabled: false when the environment has no Scheduler. |
scheduler_runs_list | read-only | The run history of an environment's Scheduler jobs, newest first, optionally for one job_id: status, the reason for a skipped or stopped run, exit code or HTTP status, duration, seconds counted in the app's hours, the commit a long task ran, and the last lines of a failed one. |
secrets_list | read-only | Secret and environment-variable metadata: key, scope, creator, timestamps. Never a value. With environment_id, what that environment gets: its own entries and the app-level ones it inherits. |
secrets_set | destructive | Set one environment variable or secret: key, value, is_secret (default true) and a required scope (app for every environment, or environment with environment_id). Creates the key or replaces its value (action), and lists in overrides_managed the environments where it overrides a managed variable. Needs Hosting: Edit. The value is never returned. |
secrets_unset | destructive | Delete one environment variable or secret by key and scope. A key that is not set answers deleted: false. Removing an override of a managed variable whose override_value is different or unknown needs confirm: true. Needs Hosting: Delete. |
previews_list | read-only | Pull-request preview deployments: PR number, head sha, URL, status, expiry. |
resource_usage_get | read-only | Current CPU/memory/network usage against limits, plus hosting meters for the billing period. A periodic sample. |
resource_usage_history | read-only | Time-range CPU/memory/network/throughput/latency history for one environment. |
deployment_create | idempotent | Trigger a deployment of a git_sha to the environment named by environment_id (from environments_list), like the Deploy button. git_ref is an optional label. |
deployment_rollback | destructive | Shift live traffic back to a previously succeeded deployment's revision. No rebuild. deployment_id is the earlier succeeded deployment to restore, not the one you are leaving, and the rollback acts on that deployment's own environment. In deployments_list for that environment, the newest succeeded deployment is the one serving, so pass one before it. The answer is a new deployment with trigger rollback. |
Call app_readiness_get before deployment_create: it names what would make the deploy fail in seconds and what would break the app after it. Call managed_variables_list before writing any code that reads process.env. Those variables are in neither the repository nor secrets_list, so an agent reading only your config concludes they're unset. Use github_refs_list to feed deployment_create a real git_sha: a sha that hasn't been pushed fails late during the build. Before merging into the auto-deploy branch, read auto_deploy.environment_type in environments_list: a development target lands on production when the app has no development environment, so target alone does not say where the merge deploys.
secrets_list without environment_id lists the app-level entries, the ones every environment inherits. With environment_id, it lists what that environment really gets: its own entries plus every app-level entry, marked inherited: true. An app-level entry the environment replaces with its own entry of the same key stays listed with overridden_by_environment: true, like the struck-through line the dashboard shows for it. These entries are sorted by key, so an override sits next to what it replaces, and count counts all of them.
In environments_list and app_get, base_url is where the environment answers once it has been deployed (the same value as public_url), null until its first deploy. public_url is built from platform_hostname ({slug}.the-meridian.app in production, {slug}-staging.the-meridian.app and {slug}-dev.the-meridian.app in the others). domains lists the platform domain first, with status active, not_deployed (never deployed, or its first deploy is still verifying) or disabled (hosting turned off for the organization), then each custom domain with its status, its certificate state tls (active, provisioning, failed, or null when Meridian holds none), dns_all_verified, the dns_records to add, and certificate_expires_at, ownership_expires_at and error_message. database gives the database's status, engine, and, when it failed, a sanitised error_code and error_message: the database add-on when the environment has one, otherwise the managed environment database, and null when it has neither. database_status is that same status (pending, provisioning, ready, failed, deleting or deleted). Neither tool ever gives the database host, user, name, connection name or password, and an error_message that would name one is replaced with a generic one, while error_code still says what failed.
logs_tail reads a since or until without an offset as UTC, and answers with server_time, the server's current time in UTC, next to the since and until it queried, also in UTC. A since more than five minutes after the server's time is refused with an error that gives the server time and the gap, because it could only return nothing: it usually means a local time was sent without its offset. An environment that was never deployed has no runtime, so its tail is empty and carries a note that says so.
source: "release" returns what the environment's release command printed, such as npx prisma migrate deploy: the run of deployment_id, or of the environment's latest deployment that ran one, whenever it ran. since and until filter it only when given, limit keeps its last lines, and the answer names the deployment_id it read. When source is omitted and the environment has no runtime yet, which is what a first deploy that failed at its release command leaves, logs_tail returns that release output instead of an empty tail, with a note that says so.
source: "task" returns what the environment's Scheduler long tasks printed. They run on their own machine, so their output is never in the web logs. Set since and until around a run's started_at and finished_at from scheduler_runs_list to read one run.
Webhooks
| Tool | Annotation | Purpose |
|---|---|---|
webhook_routes_list | read-only | Which Shopify topics are routed, the forward_path each is delivered to, whether Shopify accepted the subscription, and the destination itself: forward_host plus the forward_host_source it came from. |
webhook_deliveries_list | read-only | Recent inbound deliveries, newest first: topic, shop, status, attempts, the response code your handler returned, and any error. Filters: topic in Shopify's header form (orders/create, not ORDERS_CREATE), status, and limit (default 20, at most 100). See Delivery statuses. |
Together these separate the two failures that look identical from inside your code: no delivery row means Shopify never sent it (check the route); a 4xx/5xx response_code means it arrived and your handler rejected it. Neither tool returns the webhook body or headers.
Before reading "no delivery row" as "Shopify never sent it", check two things. A topic declared in your shopify.app.toml goes from Shopify straight to your app and never passes through Meridian, so it never has a delivery row (see Webhooks declared in shopify.app.toml). And forwarded webhooks only reach your production environment (an app without one: its first environment), never a development or staging environment or a local meridian dev.
Delivery statuses
status | What it means | What to do |
|---|---|---|
processed | Handled by Meridian, forwarded to your app, or both, with a 2xx answer | Nothing. If your code did nothing, check that your handler switches on the topic in its header form (orders/create) |
failed | Your app refused the forward, or it could not be reached. error names the status and the path | 404/405/410: serve that path or change the forward path. 401/403: see Retries and permanent failures. 3xx: remove the redirect |
ignored | Meridian had nothing to do with it. error says why: Forwarding disabled for this topic. (no forward path), No app runtime target resolved for webhook. (no deployed environment to forward to), a deleted app, or a newer shop/update that replaced it | Add the forward path on Pub/Sub, or deploy the app |
received | Being processed, or waiting for a plan change on that store to finish (retried automatically) | Wait and list again |
blocked | Held because the app is past its plan's Pub/Sub allowance. Released when the allowance allows | See Plan comparison |
dropped | Discarded over the allowance. Only on deliveries recorded before September 24, 2026 | Nothing |
In webhook_routes_list, each route's registration counts the stores where Shopify accepted the subscription (registered_shops) and where it did not (failed_shops, with last_error). A store Meridian could not reach at all, because its token was revoked or can't be renewed, or Shopify refused the request, counts as failed on every topic it hasn't registered, and its last_error starts with Could not reach followed by the store. A store that uninstalled your app drops out of these counts the next time you save the topic set.
forward_host is the origin Meridian really posts to, and forward_host_source says which destination won: external (the verified external domain you selected as the forward host), environment (your app's Meridian deployment), or platform. A platform source is Meridian's own receiver, the last resort when an app has neither: forwarded events stop there and never reach your app, and forward_url then gives the single URL they go to. Both are null when nothing is routed at all.
reconcile_available says whether Meridian can reach the stores that already installed your app, which it can only do when the app is deployed on Meridian. When it is false, Meridian can't register topics on those stores itself: the SDK registers your topic set on each store when that store authenticates your app (see Re-registering webhooks). Managed topics are in that set from install on. A route you added reaches a store only at that store's first sign-in after you added it, so each such route carries sign_in: installed_shops, and awaiting_shops, the installed stores that haven't signed in since. A sign-in within five minutes of adding the route still counts as awaiting, because the SDK can serve the topic set it cached before. sign_in is null on managed topics, and on every route when reconcile_available is true.
Shopify API alerts
| Tool | Annotation | Purpose |
|---|---|---|
shopify_alerts_list | read-only | Open API-deprecation alerts: the changelog entry, severity, migration deadline, matched code references, and whether a fix suggestion exists. |
shopify_alert_get | read-only | One alert plus its stored fix suggestion, if generated. |
Both need the Shopify API alerts: View permission on the app.
Databases
| Tool | Annotation | Purpose |
|---|---|---|
dev_database_get | read-only | Your own developer database for the app: status, storage usage, lifecycle timestamps, recent migration runs. Metadata only. |
dev_database_migrate | idempotent | Record a migration run that already happened locally. It does not execute one. |
dev_database_reset | destructive | Drop and recreate your developer database schema. Requires confirm: true. The database comes back empty: no migration runs, so apply them again with meridian db reset --yes --migrate or meridian migrate. |
database_schema_get | read-only | The table, column and index structure of an environment's managed database. Structure only, never rows. |
Developer database tools only ever reach the caller's own database, never a teammate's, even for an organization owner. Read database_schema_get before writing a migration or query against a deployed environment: the live schema is whatever the last applied migration produced, and your repository may not agree with it.
CRM
| Tool | Annotation | Purpose |
|---|---|---|
custom_fields_list | read-only | The app's custom field definitions: handle, type, the options a select field allows, and whether the field is readable by your app. Optional shop_domain also returns that store's values and needs crm.merchants.view. |
custom_field_values_set | idempotent | Set custom field values on a store, keyed by handle. A null value clears one, at most 20 per call. Writes through the same single writer the dashboard uses, so the custom field changed automation trigger fires exactly as it would otherwise. |
crm_segments_list | read-only | Segment definitions and conditions (not membership dumps). |
crm_segment_get | read-only | One segment's definition and conditions. |
Emails
| Tool | Annotation | Purpose |
|---|---|---|
emails_list | read-only | Email templates for the app: name, status, subject, timestamps. Never HTML or design. Newest first, 20 per call by default (limit up to 100). While next_cursor is not null, call again with it as cursor and the same status and search to read the next page. |
email_get | read-only | One template's metadata. Never the body. |
emails_variables_list | read-only | The merge-tag catalog available when authoring subjects and bodies. Optional shop_domain swaps the samples for that store's values and also needs crm.merchants.view. A value the store does not have reads empty, such as its Shopify Partner data while the store is known only from its install. Each variable has sample_source (store or placeholder), and store_found tells whether Meridian knows the store. |
email_create | write | Create an inactive draft (name, optional subject and preview text). Status is always forced inactive; design/HTML cannot be set through MCP. |
email_update | write, idempotent | Update an email's name, subject, or preview text. Cannot activate or edit the body. An active email must keep a subject, so clearing it is refused until the email is deactivated. Like a save in the dashboard, it also updates the Send email steps of every automation that sends the email, so their next send uses the change. |
An agent never writes an email body: email_create and email_update take no design or HTML. The one body Meridian MCP puts in an email is Meridian's own starter copy, when automation_create_from_template copies a catalog template, the same body Use this template creates in the dashboard. Edit the body and activate in the dashboard. MCP never live-sends.
Automations
| Tool | Annotation | Purpose |
|---|---|---|
automations_list | read-only | Automations with status, node count, and timestamps. |
automation_get | read-only | One automation's config and graph. Graphs strip emailHtml; node ids are remapped to public node_id values. |
automation_runs_list | read-only | Recent runs for an automation. |
automations_metrics_get | read-only | Aggregate run metrics. |
automations_catalog_get | read-only | Builder catalogs: triggers, conditions, actions and templates the graph can use. A template's graph can be passed as is to automation_update; its Send Email steps have no emailUuid yet; automation_create_from_template copies a template with its emails. |
automation_create | write | Create an inactive draft (name, optional description of up to 2,000 characters). |
automation_create_from_template | write | Copies a catalog template (template_key from automations_catalog_get) into the app, as Use this template does: an inactive automation and, for each Send Email step, a new inactive email with the template's subject, preview text and starter body, attached to that step. Takes no body from the agent. Segments, Slack channels, custom fields and usage views stay to choose. Each call makes a new copy. Needs Create automations, plus Edit emails when the template sends email. |
automation_update | write, idempotent | Update name, description (up to 2,000 characters), and/or draft graph. Graph updates only while inactive; no emailHtml. Nodes are identified by node_id and edges by edge_id (id and key are accepted too). A Send Email step references an email by emailUuid, and Meridian fills its subject, preview text and HTML from that email, so an emailSubject the graph carries is replaced. |
automation_test_run | write, idempotent | Dry-run an automation against a store (or synthetic store) and return the trace. Nothing is sent, metered, or persisted. A real store (shop_domain) also needs crm.merchants.view. A synthetic store does not. A synthetic custom_store takes subscription_status (installed, frozen or uninstalled), plan_name and optionally email; without email, Send Email steps trace as blocked and nothing is sent. |
Discounts
| Tool | Annotation | Purpose |
|---|---|---|
discounts_list | read-only | Plan Builder discount codes: name, type, value, status, duration. |
discount_get | read-only | One discount's detail. |
discount_create | write | Creates a discount: a code merchants type at subscribe, or an automatic one (auto_apply) with no code. Percentage or fixed amount, forever or for a number of billing cycles, for every plan or some (plan_ids), every store or some. |
discount_update | write, idempotent | Edits a discount: only the fields sent change. Deactivate it with status: inactive. |
The write tools follow the dashboard's discount rules and need Plan builder: Edit on the app:
- A code is unique per app and stored uppercase. A percentage is capped at 100.
- A write that leaves an automatic discount active needs
confirm: true, because it applies by itself to every new subscription it matches. Renaming one or editing its description does not. A code discount, and any inactive discount, never needs it. - A subscription keeps a discount it got when it subscribed, even after the discount is deactivated.
- Creating a discount counts against the app's discount allowance, as in the dashboard.
Resources and prompts
Two resources give the agent retrievable context: meridian://docs/{path} (Meridian's public product documentation, the same pages at help.the-meridian.ai; empty path returns an index of .md/.mdx paths). Prefer docs_search mid-task and meridian://apps/{app}/config (an app's whole configuration as one JSON document).
Two prompts arrive pre-filled with live data:
integrate_sdk: a guided walkthrough for wiring@the-meridian/sdkinto a Shopify embedded app, pre-filled with that app's real feature and event keys, types, and per-plan values. Optionalsurfacenarrows it toprovider,pricing,usage, orserver.debug_failed_deploy: a guided investigation of a failed deployment, pre-filled with its real status, error, and recent build events, followed by an ordered set of follow-up calls.
What Meridian MCP never returns
No tool ever returns a secret value, not for a secret and not for a plain environment variable. An agent can confirm a variable exists and is spelled correctly, which is what almost every "missing env var" investigation actually needs.
secrets_listandmanaged_variables_listreturn metadata only, never values and never the secret store reference.secrets_settakes a value and never returns it, andsdk_credentials_settakes the Shopify client secret and never returns it.dev_database_getreturns no password, connection string, or certificate. Connect with the Meridian CLI (meridian dev).emails_list/email_getreturn metadata only, never HTML or design.webhook_deliveries_listreturns no body and no request headers.- Internal identifiers and internal-team-only flags never appear.
Some things are intentionally absent, because doing them through an agent is a worse idea than doing them in the dashboard: reading rows from your databases, deleting plans, features or discounts, saving a new version of a plan, live email sends, activating automations, and account administration (billing, team, roles, auth settings). Store membership exports and report runs stay dashboard-only; CRM definitions (custom fields, segments) and Grow config are the exception.
Also dashboard-only, so an agent hands them to you: bringing a build forward to staging or production (deployment_create with the same git_sha builds a new deployment, it doesn't bring the verified image forward), webhook topics, forward paths and the forward host, the Shopify Partner connection, the auto-deploy branch and target (environments_list returns them), the always-on server, and adding a database or a domain. Deleting an environment is dashboard-only too.
Mutations
Twenty-five tools write; the other thirty-nine only read. Twenty-four of them change something, and every successful change is recorded in the organization's activity log with the tool that made it. The twenty-fifth, automation_test_run, is a dry trace that changes nothing and leaves no entry.
events_createadds one metered-usage event to the catalog. It does not touch per-plan terms.feature_create/feature_updateadd a feature or rename one. A plan grants it throughplan_createorplan_update.plan_createwrites a draft plan.plan_updateedits a plan, draft or active, and is refused when the change would cost its live subscribers more.plan_activateputs a plan live: merchants can subscribe right after, and pay if it is paid. Requiresconfirm: true, and is refused for a paid plan while Shopify billing is not set up.plan_deactivatetakes a plan off the pricing page. Its subscribers keep it.secrets_setcreates or updates one environment variable or secret, in any environment, production included, with the permission the dashboard needs for it (Hosting: Edit).scopeis required, so a forgotten one never writes to every environment. An existing key keeps its kind: changingis_secretis refused, so unset the key and set it again. The value goes in and never comes out, and it reaches the app at its next deploy (environments_listreportsconfig_pending_deploy). Names Meridian always sets itself (MERIDIAN_APP_ID,MERIDIAN_API_URL,MERIDIAN_OAUTH_CLIENT_ID,MERIDIAN_OAUTH_CLIENT_SECRET) and theHOSTING_prefix are refused.secrets_unsetdeletes one by key and scope (Hosting: Delete). A key set for every environment can't be deleted through one environment: the call is refused and says where the key lives. When the key overrides a variable Meridian manages, deleting it gives that variable back to Meridian at the next deploy (restores_managed). With the same value, nothing changes for your app and the call goes through. With adifferentorunknownone, it is refused untilconfirm: true, also when a key set for every environment takes over from the deleted one. A variable of a ready add-on (REDIS_HOST, for example) and theDB_HOST,DB_PORTandDB_SSL_CAMeridian sets for a database the app reaches over TCP count as managed ones, and asunknown.discount_create/discount_updatewrite a discount. Leaving an automatic discount active requiresconfirm: true.environment_createadds a development or staging environment (Hosting: Edit). The plan decides how many of each an app may have, and the environment runs in the app's region. It never creates a production environment. Adding a development environment changes where pushes land for an app whose auto-deploy target isdevelopment: they deployed to production while there was none, and deploy to the new environment from then on.environments_listreturnsauto_deploywith the environment a push lands on.environment_updatechanges an environment's settings (Hosting: Edit). The release command and the health check path apply at the next deploy. The port and the compute settings are applied to the running service on save, with no deploy, so a wrong port takes the running app down. The region, the environment type and the always-on server can't be changed. On development and staging it writes at once. On production it requiresconfirm: true.sdk_credentials_setsaves the Shopify client ID and client secret (Applications: Edit). The pair belongs to the app, so every environment gets it at its next deploy and Plan Builder billing uses it: the call always requiresconfirm: true. It replaces a credential and never clears one. The secret goes in and never comes out.deployment_createis idempotent on(environment_id, git_sha): repeating it while that deployment is in flight returns the same one. A different sha while a deployment is active is refused: one active deployment per environment. It deploys to the environment you name, production or a development or staging one, with the same permissions as the dashboard.deployment_rollbackshifts live traffic (annotated destructive). Refused if the target didn't succeed or the environment has another deployment in progress.dev_database_migraterecords a run; it does not execute one.meridian migrateruns the migration locally and records it automatically.dev_database_resetdestroys every table and row in your developer database schema. Requiresconfirm: true.custom_field_values_setwrites custom field values on a store and fires the automation trigger a dashboard edit would.email_createwrites an inactive metadata draft.email_updatechanges an email's metadata and, as a dashboard save does, the snapshot that every automation sending the email sends from. Neither activates, edits the body, or sends.automation_create/automation_updatewrite inactive drafts; graph updates only while inactive; noemailHtml.automation_create_from_templatewrites an inactive automation and inactive emails with Meridian's starter copy. It neither activates nor sends, and takes no body from the agent.automation_test_runis a dry trace: no mail, no metering, no persisted run.
Plan requirements
Meridian MCP is gated on the mcp plan feature, and the deploy-related tools additionally on the deploy feature. Every tier (Private, Lite, Pro, and Enterprise) includes both, so no plan change is needed. Private and Lite meter MCP calls (1,000 requests a month); Pro and Enterprise don't meter them. Every call about an app counts, tools, prompts and the meridian://apps/{app}/config resource alike.
The Plan Builder belongs to public apps, so the tools that read or write an app's plans, features and events, the integrate_sdk prompt and the meridian://apps/{app}/config resource refuse a private app with This feature is only available for public applications. On an app on the Private plan, the tools for merchant features answer that the plan does not include them, and they start on Lite.
While an organization is in demo mode, its real apps are out of reach through MCP as on the web: a call naming one answers App not found, or you do not have access to it.
| Refusal | What it means |
|---|---|
| This app's Meridian plan does not include the Meridian MCP feature. | The app's plan lacks mcp. Nothing works for that app. |
| This app's Meridian plan does not include the Deploy feature. | The app's plan lacks deploy. The deploy-plane and webhook tools refuse; Plan Builder, Grow, Shopify alert, and developer database tools keep working. |
| Deployment is unavailable until a plan is chosen: … | The organization is on its free trial and has not chosen the plan that starts when it ends. deployment_create refuses until someone with Billing: Manage chooses one from the app's Hosting or billing page. Nothing is charged before the trial ends. See Hosting during the trial. |
| This app's Meridian plan does not include the Logs feature. (or the Emails or Automations feature) | The app's plan lacks that feature: logs_tail, or the email and automation tools, refuse for that app. |
| This app has used its … monthly MCP requests. | A Lite app reached its 1,000 requests for the month. Wait for next month, or move the app to Pro. |
| … requires two-factor authentication. … | The organization requires 2FA and your account has none. Set up an authenticator app or a passkey in your account settings (2FA), then retry. |
| Demo mode is on. Turn it off in organization settings to make changes. | Every write refuses while the organization is in demo mode. |
| App not found, or you do not have access to it. | The app_id is wrong, belongs to an organization you can't reach, or your role lacks the permission the tool needs (for example Hosting: Edit and hosting.promote for deployment_create to production, or shopify_alerts.view for the alert tools). The two cases read the same on purpose, so a tool can't be used to probe for apps you can't see. Re-run apps_list, then ask an admin to grant the missing permission through a role. |
Versioning
The server reports its version on connect and follows semver. New tools, new resources, and new optional fields on an existing tool's output bump the minor version. A breaking change to an existing tool's contract, meaning a removed or renamed field or changed semantics, bumps the major version.
| Version | What changed |
|---|---|
1.21.0 | Added three write tools: environment_create (a development or staging environment), environment_update (release command, health check path, port and compute settings) and sdk_credentials_set (the Shopify client ID and secret). A change that reaches production needs confirm: true. Every MCP change now carries via: mcp in the activity log. environments_list returns each environment's release_command and always_on, and with app_get a new auto_deploy block: enabled, branch, target, and the environment_type and environment_id a push really deploys to. app_readiness_get adds the auto_deploy check, which warns with auto_deploy_production_branch_unprotected when pushes deploy to production from a branch GitHub or GitLab reports as unprotected. |
1.20.0 | Added scheduler_jobs_list and scheduler_runs_list for the Scheduler add-on. logs_tail accepts source: "task" for the output of the environment's Scheduler long tasks. |
1.19.0 | On connect the server also sends its title (Meridian), a description, the address of this page and the Meridian icon (SVG and a 128 px PNG), so clients and directories can show it. Every tool declares all four behaviour hints: reads and updates are idempotent, *_create and deployment_rollback are not. Input limits (minimum, maximum, default) are now in each tool's input schema instead of only in its text, and the fields whose description already said they could be cleared with null now declare it: subject and preview_text on email_update, description on automation_update. The server instructions and every tool description fit in 2 KB, the length Claude Code shows. |
1.18.0 | Added the optional source argument to logs_tail: web (the default, unchanged), worker for the Worker add-on's background process, or all for both merged by time, where each line carries its own source. |
1.17.0 | Added automation_create_from_template, which copies a catalog template into an app as an inactive automation with inactive emails holding Meridian's starter copy. An agent still never supplies an email body. |
1.16.0 | Added secrets_set and secrets_unset, which write an app's environment variables and secrets, and override_value on managed_variables_list. |
1.15.0 | Automations use one naming. automations_catalog_get returns each template graph the way automation_get does (nodes node_id, edges edge_id, with the deprecated key kept next to them), so a template's graph goes into automation_update as is. automation_update accepts id, node_id or key on nodes and id, edge_id or key on edges, and stores id only. automation_test_run describes custom_store in its schema, including the subscription_status values and email. emails_variables_list gains sample_source on each variable and store_found when shop_domain is given. |
1.14.0 | Added plan_deactivate, discount_create and discount_update (an active automatic discount requires confirm: true). |
1.13.0 | Added the Plan Builder write tools: feature_create, feature_update, plan_create, plan_update, and plan_activate (requires confirm: true). A refusal from the Plan Builder (PLAN_LOCKED, SHOPIFY_BILLING_NOT_READY, an older plan version) now reaches the agent as its message and code. |
1.12.0 | deployment_get follows a deploy to its end: wait_until: "finished" waits up to 50 seconds, finished and steps are new, and events now come newest first by default, keep the latest lines and leave build boilerplate out (order, include_noise, boilerplate_filtered). The deployment fields of the deploy tools gain error_message_pending. A failed deployment's error_message no longer repeats Cloud Run's port and timeout advice for a crash at boot, quotes the failing build step's first error block, and drops npm's update notices. |
1.11.0 | Added app_readiness_get, the readiness checks a deploy runs before its build. |
1.10.0 | Fixes empty answers that read as real ones. secrets_list with environment_id now also lists the app-level entries the environment inherits, with inherited and overridden_by_environment, so its count counts them too. logs_tail refuses a since more than five minutes ahead of the server and returns server_time, with since / until echoed in UTC, and a note on a never-deployed environment. environments_list and app_get gain platform_hostname, public_url, domains and database, and their database_status now reads the database add-on before the legacy managed database. |
1.9.0 | Added events_create, which adds a metered-usage event to an app's catalog. |
1.8.0 | environments_list gains config_pending_deploy and config_changed_at. |
1.7.0 | Added docs_search and docs_get over this documentation site. |
1.6.0 | Added sanitised error_message on failed previews and developer databases, and database_error_code / database_error_message on environments_list when provisioning failed. |
1.5.0 | Renamed the product to Meridian MCP (feature key developer_mcp became mcp), and added Grow tools for emails, automations, CRM segments, and discounts (reads, inactive draft writes, and automation_test_run). |
1.4.0 | Added custom_fields_list and custom_field_values_set. |
1.3.0 | Added the optional deployment_id, min_severity, contains, and until arguments to logs_tail, changing no existing field's semantics. |
1.2.0 | Added the read-only resource_usage_get and resource_usage_history. |
1.1.0 | Added six read-only tools: managed_variables_list, github_refs_list, previews_list, webhook_routes_list, webhook_deliveries_list, and database_schema_get. |
Troubleshooting
| Symptom | Cause and fix |
|---|---|
| The client asks to authenticate again, or every call fails as unauthorized | The connection was revoked (or the token invalidated). Reconnect from the client and approve again. |
events_create says the key is already used by a usage view | Event keys and usage view keys share one namespace per app. Pick another key, or use the existing view. |
plan_activate or plan_update answers SHOPIFY_BILLING_NOT_READY | The plan is paid and the app cannot charge through Shopify yet. The message names what is missing: the client ID or client secret (on the app's Meridian SDK page) or the Partner app connection (on Integrations). No MCP tool sets these, so hand the developer the dashboard link from the message. A SHOPIFY_API_KEY or SHOPIFY_API_SECRET set with secrets_set does not count. Then retry. A free plan activates without them. See Paid plans need Shopify billing set up. |
plan_activate answers PLAN_BUILDER_UNAVAILABLE | Meridian can't read the app's Shopify session store, which every activation needs. The message says why: the app isn't hosted on Meridian, its database has no Session table, no store has installed the app yet (install it once on a development store), or the check failed. See What the session store can block. |
plan_update or plan_activate answers PLAN_NOT_LATEST_VERSION | The plan was saved as a newer version since you read it. Read plans_list again and use the current version. |
plan_create or plan_update answers PLAN_VALIDATION_ERROR | The plan breaks a rule the message names, for example a second event with an overage rate above 0, or a yearly price on a plan that charges for usage. Fix that field. |
A write answers USAGE_VIEW_PLAN_LOCKED | The event has a usage view that a plan prices. Remove the view from those plans first. |
A write answers Use x_y instead of xY | Meridian MCP arguments are snake_case (price_monthly, feature_id). |
plan_update answers PLAN_LOCKED | Stores pay for this plan, and the change would cost them more. Save it as a new version from the plan's page in the dashboard. |
discount_create or discount_update answers that confirm was not supplied | The write would leave an automatic discount active. Nothing changed. Have the agent call it again with confirm: true once you have decided. |
plan_activate answers that confirm was not supplied | Nothing changed. The agent has to call it again with confirm: true, once you have decided to offer the plan. |
| The agent invents feature or event keys that don't exist | It skipped the catalog. Point it at features_list / events_list, or run the integrate_sdk prompt. |
| The agent invents platform behaviour that doesn't match Meridian | It skipped the docs. Point it at docs_search (then docs_get for the full page), and use live catalog tools for real feature/event keys. |
meridian://docs/ paths from an older client no longer resolve | Paths now match the public Mintlify tree (for example mcp-server.mdx), not the old internal codex layout. Re-read the empty-path index. |
deployment_create answers A deployment is already in progress for this environment (CONFLICT) | One deployment runs per environment. Follow the running one with deployment_get and wait_until: "finished", then deploy again. |
deployment_create answers Deployment is unavailable because … (APP_PLAN_REQUIRED) | The app has no plan, its free trial has ended, or the organization is suspended. Someone with Billing: Manage fixes it from the app's billing page. A hosting hold (Meridian turned off hosting for this organization) is lifted by Meridian only: write to the address in the message. |
| A deployment fails | Read its error_code and error_message with deployment_get. See Why a deploy fails. Run app_readiness_get after an invalid_config. |
dev_database_reset or dev_database_migrate says you have no developer database yet | Developer databases are created by the CLI. Run meridian dev once in the linked project. See Running your app. |
database_schema_get says the environment has no managed database add-on | The environment has no hosted database. Add one on Hosting > Database, or read your developer database with dev_database_get. |
entitlements_explain answers No shop install found for shop domain | Pass the store's *.myshopify.com domain, for a store that has installed the app. |
| Calls start failing after a burst of activity | Tool calls are rate limited per user (120 per minute). deployment_create, deployment_rollback, dev_database_reset, secrets_set and secrets_unset share a tighter budget of 10 per minute, the one the dashboard's deploy, rollback and reset buttons use. Wait and retry. |
| The client can't complete registration | Dynamic client registration is rate limited per IP. Wait before retrying rather than re-adding the server repeatedly. |
The agent expects dev_database_migrate to run the migration | It doesn't. Run meridian migrate locally. |
The agent expects email_create or automation_create to go live | Creates are always inactive. Activate the emails, then the automation, in the dashboard. |
This documentation is built and hosted on Mintlify, a developer documentation platform.