Ecomhint MCP documentation

Server endpoint

Use the same Streamable HTTP endpoint in every supported client.

The easiest place to copy it is your MCP page, where you can also review active clients and your shared audit credits.

Connect Claude

1. In Claude, open Customize, then Connectors.
2. Select +, choose Add custom connector, and paste the endpoint above.
3. Add the connector, select Connect, and sign in to your Ecomhint account.
4. Review and approve the requested permissions.
5. In a conversation, use +, then Connectors, to enable Ecomhint.

On a Claude Team or Enterprise workspace, an Owner must add the custom connector under Organization settings first; members then connect their own Ecomhint accounts. See the current Claude instructions if the labels in your account differ.

Connect ChatGPT

1. Open Settings, choose Security and login, and enable Developer mode.
2. Open ChatGPT Plugins, select +, and enter the Ecomhint name and description.
3. Under Connection, choose a public endpoint and paste the URL above.
4. Create the connection and review the discovered tools and permissions.
5. Add Ecomhint from the tools menu in a new conversation.
6. On the first protected action, sign in to Ecomhint and approve access.

Until the public Ecomhint listing is approved, this is a developer-mode setup. Developer mode availability depends on your ChatGPT account and workspace policy. See the official OpenAI instructions if the interface changes.

Headless clients and API keys

Prefer OAuth whenever the client can open a browser, as Claude Code and Cursor can. For a client that cannot, such as a script or a CI job, create a named key under MCP. The full key is shown once.

• Send it as Authorization: Bearer ehk_….
• A key signs in as your Ecomhint account, not as one store.
• A key can do everything an approved client can, starting audits included, until you revoke it.
• Keep it outside source control and logs. Create separate named keys for separate clients.
• You can have up to five active keys.

Permissions

The sign-in screen can also ask to stay connected. That lets the client renew its access on its own, so it does not ask you to sign in again each time the access runs out. Revoking the client ends it.

An audit reads the public storefront the way a visitor does, and everything a tool writes lands inside your Ecomhint account.

What a connected client cannot do

• Reach your store admin, orders, customers, or payments.
• Accept a store login or password. Those go in Store Settings.
• Stop an audit that has already started.
• Mark a task Verified. Only a later audit does that.
• Remove a project, delete a report, or change your plan. Those stay in the dashboard.
• Run two audits at once on your account.

Stores and projects

A project in Ecomhint is one store, shown by its domain. Every store your account has audited or saved is a project, and the connection works with all of them. get_account lists them and marks the active one.

• The active store is the default. The tools use it when you name no store, and the dashboard shows it.
• Name another store and the tools use that one. run_audit audits it without switching the active store, so the dashboard stays where you left it. To see that audit on the web, pick the store in the project switcher.
• set_store switches the active store. The client reads the address back first and switches only after you agree. You can switch as often as you like, in the chat or on the Projects page.
• Paste a product page and the audit still runs on the whole store. Audits check the pages of the last run and discover a page they have never seen. Ask the client to pin a product, collection, or cart URL when a report says a page could not be reached or the wrong page was picked. Pinning works for any of your stores.
• Store logins stay in the dashboard. Store Settings edits the project selected in the sidebar, so switch to the store first, then save its Basic Auth login or Shopify storefront password. No tool accepts one.
• Audit tasks belong to the store whose audit found them. A task you add in the chat is not tied to a store and shows in every store's list.

Example prompts

Ask in normal language, using the finding names from your own audit. These examples show what you can ask for and the tools that provide the information or make the change. The client chooses its calls based on your request and what is already in the conversation.

Finding names work better than vague references once the conversation gets long. For example, ask “Show me the evidence for the missing mobile rating” after discussing that finding.

Cards in the chat

In clients that support MCP Apps, starting an audit can show a progress card that keeps itself up to date. When the audit finishes, that card can turn into its summary. Opening your latest audit can also show the summary, with the score, issue counts, primary blockers, weakest categories, and up to three quick wins where those details are available.

Contextual actions let you continue from the part of the report you are reading. When the client supports follow-up messages, these buttons send a question into the conversation:

• Explain all blockers asks for an explanation of every primary blocker. It appears when the report contains blocker details, with the number of blockers in the label.
• How do I fix this? asks for the selected quick win with its available evidence and fix guidance.
• Show all quick wins asks for the complete list. It appears when there are more quick wins than the preview shows, with the total in the label.
• Compare with the previous audit asks what improved, regressed, or stayed open. It appears only when an earlier audit exists.

These questions continue in the chat. Reading more findings uses the report data without opening another summary card. The separate Open full report link opens the complete report on the Ecomhint website.

In clients without card support, the same audit data remains available through the conversation.

Tool reference

Fifteen tools, in the order a client discovers them. For an initial audit overview, get_account checks your account and active store, and get_latest_report opens the newest report. get_check_result provides the evidence and fix guidance for one selected finding.

Tools that read one store take an optional store URL. Without it they use your active store. Tools that take a report id work on any of your stores.

Audit credits

• Full Access includes 10 audit credits a month, any store. At $29 a month that is $2.90 per audit.
• Audits you start on the web and audits you start from a chat spend the same audit credits.
• Credits are shared across all your stores. Auditing a second store spends one credit, the same as your first.
• One audit credit is spent the moment a run is accepted.
• Your account runs one audit at a time, on the web or in a chat. Asking again for the same store while its audit is queued or running hands back that audit and costs nothing. An audit of another store is refused until the first one finishes.
• A run that fails without producing a report gives its credit back.
• A queued audit can be canceled and gives its credit back. A running one cannot be stopped.
• An eligible incomplete report can be re-run in place up to three times without spending another credit. This is for a report with pages the audit could not reach and free re-runs remaining. The new result replaces that report. A complete report cannot be re-run for free. To check that store again, run a new audit, which spends one credit.
• Unused credits do not carry over to the next billing period.
• get_account returns how many credits are used and when they reset.

Disconnect and revoke

Remove Ecomhint in the client settings, or revoke that one client from MCP in your dashboard, where approved clients and API keys each have a Revoke button. Revoking from the dashboard takes effect at once and stops every further request from that client. Your reports, tasks, stores, and subscription stay as they are.

Troubleshooting