Connect an AI client with MCP

What this article helps you do

Connect an AI client to your shop’s Mapstore data. Model Context Protocol (MCP) lets AI applications use tools from a connected server. See the MCP overview for more information.

Mapstore provides tools to read and change stores, custom fields, lead forms, and settings. It also provides store locator analytics.

Before you start

• Open Mapstore from Shopify admin.
• Use an MCP client that supports remote Streamable HTTP connections and bearer tokens.
• Decide which data the client must read or change.

A token is a secret value that gives the client access to one shop. Each token has access options, also called scopes. These options control which tools the client can use.

Create a token

1. Open MCP in the Mapstore navigation.
2. In MCP access, select Create token.
3. Enter a Token name that identifies the client or task.
4. Under Access, select the required options.
5. Select Create token.
6. Copy the token or connection setup before you leave the page.

Mapstore selects all read options by default for a new token. Keep only read options selected when the client must not change data.

Tokens expire after 90 days. Each shop can have up to 10 active tokens. Mapstore cannot show the full token again after you leave the page.

Connect your client

1. On the MCP page, find Connect an MCP client.
2. Select your client.
3. If Setup method is available, select CLI command or Configuration file.
4. Select Copy command or Copy configuration.
5. Follow the displayed setup instructions for your client.
6. Follow the instructions under Verify.

The page provides setup instructions for Claude Code, Codex, Cursor, Hermes Agent, and OpenClaw. Mapstore adds a newly created token to the setup. For Hermes command setup, copy the token when the command asks for it.

If no token was added, replace only the placeholder token value with your token. Keep environment variable names, such as MAPSTORE_MCP_TOKEN, unchanged. Keep the token and copied setup secret. Do not add them to a public file or source repository.

For another compatible client, use these connection details:

Replace YOUR_TOKEN with your Mapstore token. Use the server URL shown in Mapstore if it differs from this example.

Choose access options

Only tools allowed by the token appear in the client’s tool list. Write access does not include read access. Select both when the client must check a record before and after a change.

To change access options, create a replacement token with the required access. Update your client setup with the replacement token. Then revoke the old token.

Check the connection

With Read stores access, send this request to your AI client:

Use Mapstore MCP to list the available tools. Call list_entities with limit 5 and includeSheetStores true. Do not change data.

Make sure the client returns a store list or an empty result without an access error. An empty result can mean the shop has no stores.

Review all stores

list_entities returns 20 stores per page by default, with a maximum of 100. It excludes sheet-managed stores unless includeSheetStores is true. The list contains summary fields. Use get_entity with a returned ID for the full store record.

Use this request with Read stores access:

Review all Mapstore stores without changing data. Call list_entities with includeSheetStores true, filter all, and limit 100. Start at page 1. Increase page until pagination.hasNextPage is false. Report draft stores, missing addresses or coordinates, and possible duplicates. Use get_entity when you need the full record. Do not guess record IDs.

With Read locator analytics access, you can also ask:

Use get_locator_analytics to review the last 90 days. Summarize searches, filters, and store clicks. Do not change data.

Locator analytics contain store locator activity. They do not contain Shopify sales analytics. The default date range is the last 90 days.

Make changes

1. Select the required read and write options when you create the token.
2. Ask the client to read the current records first.
3. Review the proposed changes and exact record IDs.
4. Ask the client to make the required changes.
5. Ask the client to read the records again to verify the result.

Tell the client to ask for confirmation before each deletion. Deleting a custom field also deletes its values.

Sheet-managed stores are read-only through MCP. Change their source data in Google Sheets. New stores created through MCP count towards your plan limit.

update_lead_form creates or replaces the full form configuration. Read the current form before you approve a replacement.

update_settings can change notification emails and supported map settings. MCP does not return secret API key values or let clients change Google API keys.

Revoke access

1. Open MCP in Mapstore.
2. Find the token under MCP access.
3. Select Revoke.
4. Confirm the revocation.

Clients that use this token immediately lose access. If you lose or expose a token, revoke it and create a replacement.

Troubleshooting

Related articles

• Mapstore admin pages
• Stores from Google Sheets
• View store locator activity