MCP - Developer documentation

The Juo MCP server gives AI assistants and agents access to your store through the Model Context Protocol. Once connected, Claude, ChatGPT, Cursor, Codex, or any other MCP client can read and manage subscriptions, customers, products, schedules, analytics, and workflows.

Server URL

https://mcp.juo.com/mcp

The server uses the Streamable HTTP transport. You can authenticate in two ways:

OAuth (the default): log in with your Juo account in the browser. See OAuth authorization flow.
Admin API key: for scripts and agents that run without a browser. See Connecting with an Admin API key.

Toolsets

The server offers two endpoints. Add one of them to a client, not both.

Endpoint	What it lists
`https://mcp.juo.com/mcp`	The core toolset: the 36 tools used most often for subscriptions, schedules, analytics, and workflows, plus three `admin-tools-*` tools that find and run the rest
`https://mcp.juo.com/mcp/all`	Every tool, listed directly

Use /mcp unless you have a reason not to. A shorter list helps the assistant pick the right tool, and it stays under client limits such as Cursor’s 40 tools. Tools outside the core set are still available: the assistant finds them with admin-tools-search and runs them with admin-tools-write or admin-tools-destructive. Keeping writes and deletions in separate tools lets your client approve one without the other.

https://mcp.juo.com/sse still works for clients set up before the move to Streamable HTTP. Use /mcp for new connections.

Connecting a client

In claude.ai, go to Customize → Connectors, click +, then Add custom connector, and enter:

https://mcp.juo.com/mcp

On Team and Enterprise plans, an owner adds it under Organization settings → Connectors. The connector is also available in Claude Desktop. Claude opens the Juo login page the first time you use it.

claude mcp add --transport http juo https://mcp.juo.com/mcp

Run /mcp in a Claude Code session and select juo to log in.

codex mcp add juo --url https://mcp.juo.com/mcp
codex mcp login juo

codex mcp login opens the OAuth login in the browser.

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "juo": {
      "url": "https://mcp.juo.com/mcp"
    }
  }
}

Cursor asks you to log in before the tools become available.

Add to .vscode/mcp.json, or to your user configuration with the MCP: Open User Configuration command:

{
  "servers": {
    "juo": {
      "type": "http",
      "url": "https://mcp.juo.com/mcp"
    }
  }
}

Start the server from the file or the MCP view and log in when prompted.

Add to Windsurf’s mcp_config.json:

{
  "mcpServers": {
    "juo": {
      "serverUrl": "https://mcp.juo.com/mcp"
    }
  }
}

Refresh the MCP servers and log in when prompted.

Add to Zed’s settings.json, or use Settings → AI → MCP Servers → Add Server → Add Remote Server:

{
  "context_servers": {
    "juo": {
      "url": "https://mcp.juo.com/mcp"
    }
  }
}

Zed starts the OAuth login on the first connection.

Add to Continue’s config.yaml:

mcpServers:
  - name: juo
    type: streamable-http
    url: https://mcp.juo.com/mcp

Reload Continue and log in when prompted.

Clients that only run local (stdio) servers can connect through mcp-remote:

npx mcp-remote https://mcp.juo.com/mcp

Use this as the server command in the client’s configuration. mcp-remote opens the OAuth login in the browser.

OAuth authorization flow

The Juo MCP server uses the standard OAuth 2.0 authorization code flow with PKCE. When you connect for the first time:

The client connects to https://mcp.juo.com/mcp.
The server answers that authorization is required.
The browser opens the Juo login page.
You log in with your Juo account, pick a store, and grant access.
The client exchanges the code for an access token. You never copy a token by hand.

Tokens are scoped to one store and stored by the MCP client. You only log in again when a token expires or is revoked.

Connecting with an Admin API key

OAuth needs a person in a browser. For scripts, CI jobs, scheduled tasks, and self-hosted agents, connect with an Admin API key instead.

In the Juo admin, go to Settings → Integrations → API keys, enter a label, and create a key. Copy it right away: the key is shown only once.
Send two headers on every request to https://mcp.juo.com/mcp:

Header	Value
`X-Juo-Admin-Api-Key`	The Admin API key
`X-Tenant-ID`	The store’s myshopify domain, e.g. `my-store.myshopify.com`

Requests that carry X-Juo-Admin-Api-Key skip the OAuth flow. The same headers work on https://mcp.juo.com/mcp/all.

claude mcp add --transport http juo https://mcp.juo.com/mcp \
  --header "X-Juo-Admin-Api-Key: $JUO_ADMIN_API_KEY" \
  --header "X-Tenant-ID: my-store.myshopify.com"

In ~/.codex/config.toml, read the key from an environment variable:

[mcp_servers.juo]
url = "https://mcp.juo.com/mcp"
http_headers = { "X-Tenant-ID" = "my-store.myshopify.com" }
env_http_headers = { "X-Juo-Admin-Api-Key" = "JUO_ADMIN_API_KEY" }

{
  "mcpServers": {
    "juo": {
      "url": "https://mcp.juo.com/mcp",
      "headers": {
        "X-Juo-Admin-Api-Key": "your_api_key",
        "X-Tenant-ID": "my-store.myshopify.com"
      }
    }
  }
}

An input variable keeps the key out of the file. VS Code asks for it when the server starts:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "juo-api-key",
      "description": "Juo Admin API key",
      "password": true
    }
  ],
  "servers": {
    "juo": {
      "type": "http",
      "url": "https://mcp.juo.com/mcp",
      "headers": {
        "X-Juo-Admin-Api-Key": "${input:juo-api-key}",
        "X-Tenant-ID": "my-store.myshopify.com"
      }
    }
  }
}

{
  "mcpServers": {
    "juo": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.juo.com/mcp",
        "--header", "X-Juo-Admin-Api-Key:${JUO_ADMIN_API_KEY}",
        "--header", "X-Tenant-ID:my-store.myshopify.com"
      ],
      "env": {
        "JUO_ADMIN_API_KEY": "your_api_key"
      }
    }
  }
}

A custom agent can call the server directly:

curl https://mcp.juo.com/mcp \
  -H "X-Juo-Admin-Api-Key: $JUO_ADMIN_API_KEY" \
  -H "X-Tenant-ID: my-store.myshopify.com" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The MCP server passes the key on to the Juo Admin API, which validates it. A wrong or revoked key doesn’t fail when the client connects. The error shows up on the first tool call.

An Admin API key gives full Admin API access to the store, so treat it like a password. Keep it in an environment variable or a secrets manager, not in a config file you commit. To revoke a key, open Settings → Integrations → API keys and click Revoke.

Building workflows with an assistant

The server includes guidance that walks the assistant through building a workflow. Assistants that follow it work like this:

Look up the catalog. workflows-catalog returns the triggers first. With a trigger type, it returns the actions, settings, customer responses, conditions, and A/B test step shape allowed for that trigger. The assistant takes every name from the catalog instead of guessing.
Create the workflow. workflows-create validates the definition. A workflow with issues is still saved, as an unpublishable draft that lists them, so no work is lost.
Fix or change it. workflows-edit changes part of a saved workflow (a step, a setting, a transition, the name) without resending the rest. It saves only valid results and refuses an edit based on an outdated copy.
Publish with your approval. The assistant asks before publishing. Several workflows can exist for one trigger, but only one is published at a time.
Measure. workflows-run-report returns runs, End steps reached, and customer responses per step, with percentages and A/B variants, for one or more workflows over a date range.

The server also provides a build-workflow prompt and a juo://workflows/catalog resource for clients that support them. Customer-facing content, such as pop-ups and polls, can’t be previewed through MCP, so check it in the workflow editor before you publish.

Workflows are never hard-deleted through MCP. Asking to delete or remove a workflow archives it, and workflows-unarchive restores it as a draft.

Available tools

Tools marked † aren’t listed on /mcp. There, the assistant reaches them with admin-tools-search and runs them with admin-tools-write or admin-tools-destructive. On /mcp/all they’re listed like any other tool.

Subscriptions

Tool	Description
`subscriptions-list`	List subscriptions with their items, discounts, and customer ID; filter with `query`, e.g. `customer:<customerId>` or `status:active`
`subscriptions-create` †	Create a subscription with billing policy, items, delivery address, and payment method
`subscriptions-update`	Change the payment method, delivery address, method or price, or the next billing date
`subscriptions-pause`	Pause an active subscription; nothing is billed until it’s resumed
`subscriptions-resume`	Resume a paused subscription
`subscriptions-cancel`	Cancel a subscription, optionally emailing the customer
`subscriptions-reactivate`	Reactivate a canceled subscription
`subscriptions-custom-attributes-create` †	Add custom attributes to a subscription; existing keys are never overwritten

Subscription items

Tool	Description
`subscriptions-items-create`	Add a product variant, optionally with a custom price and a recurring cycle limit (1 = one-time add-on)
`subscriptions-items-update`	Change an item’s quantity or its billing and delivery frequency
`subscriptions-items-delete`	Remove an item; removing the last item cancels the subscription

Subscription discounts

Tool	Description
`subscriptions-discounts-create`	Apply a discount code, or a manual percentage or fixed amount on all items, chosen items, or shipping
`subscriptions-discounts-update` †	Change a discount’s value or recurring cycle limit
`subscriptions-discounts-delete`	Remove a discount from a subscription

Schedules

Tool	Description
`schedules-list`	Preview a customer’s upcoming orders (read-only)
`schedules-list-adjustments`	List a customer’s schedule adjustments (skips, moved dates, other one-order changes)
`schedules-create`	Change one upcoming order without changing the subscription: skip it or some items, move its date, change its address, payment method, or products, or discount it
`schedules-delete`	Delete an adjustment, so the order follows the subscription again

Customers

Tool	Description
`customers-list`	Find customers by name, email, phone, or ID with `query`
`customers-create` †	Create a customer with contact details (name, email, phone, tags, note)
`customers-update` †	Partially update a customer’s profile
`customers-delete` †	Permanently delete a customer
`customers-create-payment-method` †	Attach a payment method to a customer through a supported payment provider

Products

Tool	Description
`products-list`	List products; search by title, status, or variant SKU/title with `query`, or filter by plan group
`products-create` †	Create a product with title, description, vendor, type, tags, status, and an optional image
`products-update` †	Partially update a product
`products-delete` †	Permanently delete a product
`products-add-variant` †	Add a variant to a product
`products-remove-variant` †	Remove a variant from a product
`products-assign-product-to-plan` †	Make all variants of a product available under a subscription plan
`products-remove-product-from-plan` †	Remove all variants of a product from a subscription plan
`products-assign-variant-to-plan` †	Make one variant available under a subscription plan
`products-remove-variant-from-plan` †	Remove one variant from a subscription plan

Workflows

Tool	Description
`workflows-catalog`	The triggers, actions, settings, customer responses, conditions, and A/B test step shape a workflow may use; filter by `triggerType`
`workflows-list`	List workflows (ID, name, trigger type, status); filter by status or trigger type
`workflows-get`	Get a workflow’s full definition: trigger, steps, transitions, A/B variants, layout, and status
`workflows-create`	Create a workflow; one with issues is saved as an unpublishable draft that lists them
`workflows-validate`	Check a workflow definition without saving it
`workflows-edit`	Change part of a saved workflow without resending the whole definition; saves only valid results
`workflows-update`	Replace a workflow’s name, description, trigger, or steps in full
`workflows-duplicate` †	Copy a workflow as a new draft
`workflows-publish`	Publish a draft; only one workflow per trigger type is published at a time
`workflows-unpublish`	Move a published workflow back to draft; runs in progress finish on their current version
`workflows-archive`	Archive a workflow; run history is kept
`workflows-unarchive` †	Restore an archived workflow as a draft
`workflows-visualize`	Show workflows as diagrams drawn like the workflow editor; offered only to clients that support MCP Apps
`workflows-conclude-experiment`	End an A/B test step: send every new run to the winning variant, or stop the test

Workflow runs and reporting

Tool	Description
`workflows-run-report`	How workflows perform: runs, End steps reached, and customer responses per step, with percentages and A/B variants, over an optional date range
`workflow-runs-list`	List runs across all workflows; filter with `query`, e.g. by customer, status, workflow, or start date
`workflows-list-runs`	List one workflow’s runs, with the same `query` filters
`workflows-get-run`	Get one run in full: trigger payload, customer responses, action outputs, A/B variant, outcome, error, and event timeline
`workflows-get-run-stats`	Totals for one workflow: runs per status and outcome, entries per step, A/B enrollments, and conversion rates
`workflows-export-runs`	Get a short-lived link to a CSV with one row per run

Analytics

Tool	Description
`analytics-list-metrics`	Describe the metric catalog: what each metric measures, and the filters and group-by dimensions it supports
`analytics-query`	Query one metric over a date range as a time series, with optional grouping, filters, currency conversion, or cohorts

Call analytics-list-metrics before building a query. An unsupported filter returns a 400.

Finding and running other tools

Tool	Description
`admin-tools-search`	Find the tools not listed on `/mcp` and get their input schemas
`admin-tools-write`	Run one of those tools that creates or changes data
`admin-tools-destructive`	Run one of those tools that deletes or removes data

These three are listed only on /mcp.

​Server URL

​Toolsets

​Connecting a client

​OAuth authorization flow

​Connecting with an Admin API key

​Building workflows with an assistant

​Available tools

Server URL

Toolsets

Connecting a client

OAuth authorization flow

Connecting with an Admin API key

Building workflows with an assistant

Available tools