Get started

iStores MCP Connection Guide

Connect the Claude app, Claude Code, Codex, or another OAuth-capable MCP client to your iStores account. The assistant can inspect your storefront, manage your catalog, edit theme files, and generate branding assets through the hosted iStores Design Ops server.

You do not need to install or host an MCP server.

Connection Details

Field	Value
Server name	`istores-design-ops`
MCP URL	`https://api.istores.co.il/mcp`
Transport	Streamable HTTP
Authentication	OAuth 2.0 through your iStores account
Company and store	Selected automatically from the company active when you approve access

Add the server URL without a manually configured Authorization header. Your MCP client obtains and sends the OAuth access token after you sign in.

The API key from Company settings is for the regular API. It is not accepted by the current MCP authentication flow.

Before Connecting

Use an MCP client that supports remote HTTP servers and OAuth.
Sign in to your iStores dashboard and select the company/store you want the assistant to use.
Add the MCP server using one of the instructions below.
Complete the browser login and approve the requested permissions.

If your account manages several companies, select the intended company before approving access. Changing the company in the dashboard later does not change an existing MCP token. Sign out of the MCP connection and authenticate again to connect another company.

Connect with the Claude App (Desktop / Web)

No terminal commands are needed for this setup.

Open Claude and go to Customize → Connectors, or open Connectors in your browser using the same Claude account.
Choose + Add → Add custom connector.
Enter iStores Design Ops as the name and https://api.istores.co.il/mcp as the remote MCP server URL. Click Continue.
Review the detected OAuth settings. Choose Sign in now. For OAuth client, use Claude's published identity or Register automatically. Leave your own client ID/secret and request headers empty; iStores supports automatic client identification.
Finish adding the connector. If it is not connected yet, click Connect.
In the browser, sign in to iStores, ensure the intended company is selected, and approve access.
Open a Claude chat, click + → Connectors, and enable iStores Design Ops.

Try: Inspect my current store and list its products. Do not change anything yet.

For Team or Enterprise accounts, an authorized organization administrator must add the connector first; each member then connects individually. If the app does not show the add option, use the browser Connectors page above.

See the official Claude custom connector guide.

Connect with Claude Code

Run in your terminal:

Code(bash)
 
claude mcp add --transport http --scope user istores-design-ops https://api.istores.co.il/mcp

Inside an interactive Claude Code session, open:

Code(text)
 
/mcp

Select istores-design-ops, start authentication, and complete the iStores login and permission approval in your browser. Then check the connection:

Code(bash)
 
claude mcp list

If You Already Added an API Key

Remove the old user-scoped entry, then add it again without a header:

Code(bash)
 
claude mcp remove istores-design-ops --scope user
claude mcp add --transport http --scope user istores-design-ops https://api.istores.co.il/mcp

Open /mcp again and authenticate. If the old entry was added with a different scope, remove that entry using its original scope.

A configured Authorization header prevents Claude Code from falling back to OAuth when that header is rejected. See the official Claude Code MCP documentation.

Connect with Codex

Run in your terminal:

Code(bash)
 
codex mcp add istores-design-ops --url https://api.istores.co.il/mcp
codex mcp login istores-design-ops
codex mcp list

Complete the iStores login and permission approval in the browser opened by the login command.

Configure Manually

Alternatively, add this entry to ~/.codex/config.toml:

Code
 
[mcp_servers.istores-design-ops]
url = "https://api.istores.co.il/mcp"
enabled = true

Then run codex mcp login istores-design-ops. Reload your Codex session if the new server is not visible.

For an existing entry, remove manually configured Authorization values from http_headers or env_http_headers, and remove bearer_token_env_var for this server before using OAuth. Keep only one definition of this server in the configuration that applies to your session.

See the official Codex MCP documentation.

Other MCP Clients

Add a remote HTTP MCP server with URL https://api.istores.co.il/mcp, choose OAuth authentication, and follow the browser login flow. Leave custom API key and Authorization header fields empty.

The client must support OAuth discovery and either dynamic client registration or a supported client metadata document. A client that only supports static API key headers cannot use this connection method.

What Is companyId?

companyId is the internal iStores company identifier. It is not a VAT number, storefront domain, OAuth client ID, or API key. storeId identifies the store belonging to that company.

You normally do not need to find or supply either value. The OAuth token identifies the company selected during authorization, and the server loads its store automatically.

Every current tool accepts an optional companyId. Omit it unless you specifically need to check the authenticated context. If supplied, it must match the authenticated company; it cannot select another company or repair a failed login.

If you need the value for troubleshooting, ask the assistant to call create_launch_plan without arguments and report the returned companyId and storeId. This tool reads the selected company's setup context; it does not create products or publish changes.

Code(json)
 
{
  "name": "create_launch_plan",
  "arguments": {}
}

If authentication has failed, reconnect first or ask iStores support to identify your company. Do not guess a company ID.

What the Server Can Do

Area	Available tools
Setup and inspection	`create_launch_plan`, `inspect_brand_assets`, `inspect_storefront`
Store languages	`list_languages`
Products	`list_products`, `get_product`, `create_product`, `update_product`, `delete_product`
Categories	`list_categories`, `get_category`, `create_category`, `update_category`, `delete_category`
Options	`list_options`, `get_option`, `create_option`, `update_option`, `delete_option`
Custom CSS/JS and snapshots	`read_theme`, `update_theme`, `create_snapshot`, `list_snapshots`, `rollback_snapshot`
Editable theme files	`list_theme_files`, `read_theme_file`, `update_theme_file`, `delete_theme_file`
Branding and media	`upload_media`, `update_logo`, `update_banner`
AI image generation	`check_demo_budget`, `list_brand_ai_prompts`, `generate_logo`, `generate_banner`, `generate_product_image`, `get_ai_generation_result`

Use the schemas returned by tools/list for each tool's required fields. OAuth scopes advertised by the server do not mean that a matching MCP tool exists for every regular API endpoint. For example, payment setup is handed off to the dashboard link returned by create_launch_plan.

Start with a Read-Only Request

After connecting, ask:

Code(text)
 
Use the iStores MCP connection to inspect my current store and list its products.
Use the company already authenticated by OAuth; do not ask me for companyId.
Do not create, update, delete, generate, or publish anything yet.

For a storefront redesign workflow, see iStores AI Storefront Designer.

Changes, Media, and Backups

Ask the assistant to explain changes and obtain your approval before changing a live store.
update_theme replaces the full custom CSS value. Read the existing CSS first and keep createBackup enabled; it defaults to true.
Non-empty JavaScript is blocked by update_theme. Use the editable files returned by list_theme_files for supported theme JS changes.
create_snapshot and rollback_snapshot cover custom CSS and JS only. They do not back up products, categories, options, logos, banners, or the whole store.
Theme file updates and resets create separate file snapshots by default. rollback_snapshot does not restore those file snapshots. Resetting a file with delete_theme_file restores the system version, not an earlier custom version.
Product/category/option deletion requires confirmed: true after you approve the exact ID. Theme file reset requires confirmation of the exact path.
Use public, server-fetchable image URLs for product and branding updates. Chat-local files and session-only links are not accessible to the MCP server. upload_media accepts image data; its filePath refers to a file on the MCP host.
AI generation consumes credits. Check check_demo_budget first. An insufficient balance may trigger a paid credit top-up; approve spending before generation.
Image generation is asynchronous. Poll get_ai_generation_result with the same resultId, respecting pollAfterSeconds and maxWaitSeconds. Do not start another generation while the existing job is processing. Check the completed result's data.applied before applying branding again.

Troubleshooting

Message or symptom	What to do
`Token missing` / needs authentication	Complete OAuth login. An unauthenticated connection receives HTTP 401 so the client can discover the login flow.
`Company not found` after using a settings API key	Remove the manually configured key/header and reconnect with OAuth. The settings API token does not carry the company claim expected by MCP.
`Company not found` after OAuth login	Authenticate again with the intended company selected. If it continues, contact support with the `request_id`.
`Server rejected the configured Authorization header` / OAuth fallback disabled	Remove the manually configured `Authorization` header and authenticate again.
`Invalid token`	Remove stale manual credentials and reconnect through OAuth.
`Token expired`	Let the client refresh the token, or sign in again if refresh fails.
`Invalid token audience`	Use the exact MCP URL above and obtain a token through this MCP connection. A token for another resource cannot be reused.
`companyId does not match the authenticated company.`	Omit `companyId`, or reconnect with the intended company selected.
HTTP 402 / `Payment owe detected`	Resolve the company's outstanding payment in the dashboard.
HTTP 429	Wait before retrying and reduce the frequency of requests.
OAuth `invalid_grant`	Restart authentication. The authorization code may be expired/used, the refresh token unavailable, or the callback/PKCE values mismatched.
OAuth `invalid_client`	Remove and add the server again so the client can register, then authenticate. Contact support if it persists.
Storefront inspection blocked	Use the returned storefront URL in a browser. Bot protection can block server-side inspection; provide a screenshot or relevant HTML if needed.

When contacting support, include your client name, the MCP URL, the error, and request_id when present. Do not send access tokens, refresh tokens, API keys, or complete authorization callback URLs.

OAuth Flow for Developers

MCP clients handle these steps automatically; merchants do not need to create a client ID or exchange tokens manually.

Step	Endpoint / behavior
Discover the protected resource	`GET https://api.istores.co.il/.well-known/oauth-protected-resource/mcp`
Discover authorization endpoints	`GET https://api.istores.co.il/.well-known/oauth-authorization-server`
Register a client when needed	`POST https://api.istores.co.il/mcp/oauth/register`
Request authorization	`GET https://api.istores.co.il/mcp/oauth/authorize`; redirects to the dashboard for login and consent
Exchange the authorization code	`POST https://api.istores.co.il/mcp/oauth/token` with `grant_type=authorization_code`, `client_id`, `redirect_uri`, `code`, and `code_verifier`
Call MCP	The client sends the issued access token as `Authorization: Bearer <access_token>` to `/mcp`
Refresh access	The token endpoint accepts `grant_type=refresh_token`, `client_id`, and `refresh_token`

The flow uses Authorization Code with PKCE (S256). Authorization codes are single-use and valid for five minutes. Default access token lifetime is one hour; default refresh token lifetime is 90 days. Use the token response's expiry fields rather than hard-coding these defaults.

Use the MCP resource URL https://api.istores.co.il/mcp as the OAuth resource. The token is tied to the company selected at consent and includes its identifier. These MCP endpoints are separate from the regular SSO integration.

Last modified on October 11, 2026

Modules API iStores AI Storefront Designer