AlterVision MCP Connector 🤖

What it is

AlterVision's official connector gives your AI assistant read-only access to your brick-and-mortar store metrics, letting you ask in natural language about visitor traffic, conversion, goals, races and non-conversion reasons — without opening the dashboard or building a report.

It is an MCP (Model Context Protocol) server, the open protocol that standardizes how AI assistants access external tools and data. Any MCP-compatible client can use it — Claude and ChatGPT, among others.

Server URL	https://api.painelalter.com/mcp
Transport	Streamable HTTP
Authentication	OAuth 2.1 with PKCE and client ID metadata documents (CIMD)
Consent screen	https://painelalter.com/mcp/authorize
Tools	9, all read-only
Compatibility	Any MCP client supporting remote HTTP and OAuth

Read-only

All connector tools only query information. None of them writes, changes or deletes data in PainelAlter.

Prerequisites

• An active AlterVision account at painelalter.com.
• Access to at least one store.
• For some tools, stores with the AlterVez product enabled — see the Tool reference.

Stores without AlterVez

The races, non-conversion reasons and transcription tools only report stores with AlterVez enabled. A store without AlterVez is silently excluded from the result — it does not raise an error. If you expect a store and it does not show up in those responses, it most likely does not have the product enabled.

How to connect

The steps vary from client to client, but the procedure is the same everywhere: add a remote connector by providing the server URL. There is no prior registration and no API key to generate — as soon as you add the connector, the OAuth flow starts on its own.

https://api.painelalter.com/mcp

In Claude

1. Open Settings → Connectors.
2. Choose add custom connector.
3. Paste the server URL.
4. Claude opens the consent screen at https://painelalter.com/mcp/authorize. Sign in with your AlterVision dashboard credentials.
5. Approve the access. The connector becomes available in your conversations.

TODO

Add screenshots for each step in Claude (Settings → Connectors, the URL field, the PainelAlter consent screen and the approval screen).

In ChatGPT

ChatGPT supports adding remote MCP connectors in its connector settings. Once you provide the server URL, the rest of the flow is identical: the PainelAlter consent screen opens, you sign in with your credentials and approve the access.

TODO

Confirm and describe the exact path in ChatGPT's current interface (which plans offer the feature, the menu name and whether any developer mode is required), and add the corresponding screenshots.

In other MCP clients

Any client that supports remote MCP servers over HTTP with OAuth authentication can use the connector. Provide the server URL in whatever format the client expects and complete the sign-in on the PainelAlter consent screen.

Client-independent

The connector does not depend on any specific assistant: the same 9 tools, the same data scope and the same authentication flow apply to every client.

The generated token grants access to exactly the stores you already see in the dashboard — no more, no less.

What you can ask

You do not need to know the tool names or the store ids: ask the way you would ask an analyst. Some examples:

Traffic and conversion

• "How was conversion across my stores this week?"
• "How many visitors did my downtown store get per day last month?"
• "Which store had the best UPT in August?"
• "Were the cameras up the whole period?"

Goals

• "Am I hitting this month's goal?"
• "If this pace holds, where will my goals land?"
• "Which sellers are contributing to store X's goal?"

Races

• "Who is winning the race?"
• "What does the conversion race standing between stores look like?"
• "Which seller is ahead in store X's race?"

Non-conversion

• "Why aren't customers buying at store X?"
• "How much revenue did I lose to stockouts last month?"
• "Did non-conversion reasons get worse compared to the previous period?"
• "What did customers ask for that we didn't have? Show me the interactions."

Tool reference

Every tool that takes a period requires dateBegin and dateEnd in YYYY-MM-DD format. All of them accept an optional storeIds (a list of ids); omitting it means "every store the user has access to".

Tool	What it returns	Requires AlterVez
whoami	Id, username and email of the authenticated user. No parameters.	—
get_stores	Stores the user has access to, with id, alias and name. No parameters. Use it to resolve a store name into the id the other tools expect.	—
get_flow_per_day	Visitor count and daily average per store, day by day.	—
conversion_rate_per_date	Revenue, number of sales, conversion rate, UPT, average price per item and camera uptime, per store.	—
metas_infos	Compares actual revenue, traffic, conversion and UPT against the projection of each active goal in the period, and projects where each goal will land.	—
corridas_infos	Races between stores or between sellers of a store, with KPI, dates and participants.	Yes
get_noc_reason_classifications_available	Classifications and subclassifications a non-conversion reason can have. No parameters.	—
noc_reasons_stats	Distribution of non-conversion reasons: count, share, lost revenue and variation against the previous period of the same length.	Yes
search_non_conversion_transcriptions	The interactions behind the non-conversions, with the seller's own account of what the customer asked for.	Yes

Tool details

get_flow_per_day

Extra parameters: includeDetails (day-by-day breakdown) and flowPreference (individual or group, overriding the user's saved preference). Stores with no measured traffic in the period are omitted.

conversion_rate_per_date

Extra parameters: includeDetails and flowPreference. The per-item metrics (UPT and average price per item) only make sense in stores with ERP sales integration.

metas_infos

Extra parameters: includeDetails and includeSellers. Supports tiered goals. It returns one entry per goal, not per store — a single goal may span several stores.

corridas_infos

Extra parameters: category (store or seller), kpi (conversion, numberOfSales, revenue, averageTicket, pa) and includeRanking (current standing).

get_noc_reason_classifications_available

Call it before noc_reasons_stats and search_non_conversion_transcriptions to discover the valid filter values.

noc_reasons_stats

Extra parameters: includeSubclassifications, includeStoreBreakdown and sellerIds — omitting sellerIds means no seller breakdown; an empty array breaks down by every seller.

search_non_conversion_transcriptions

Parameters: mainClassifications (required, at least one), subClassifications and sellerIds. It brings the seller's own account of what the customer asked for — stockouts, brands, payment methods, price objections.

Result limit

Results are capped at 100 interactions in total, so filters need to be narrow.

Glossary

Term	Meaning
Interactions (atendimentos)	Recorded interactions between a seller and a customer in the store.
AlterVez	AlterVision product that enables recording interactions, non-conversion reasons and races.
Races (corridas)	Competitions between stores or between sellers of the same store, played out on a KPI.
Goals (metas)	Targets defined in the dashboard for revenue, traffic, conversion and UPT. They can be tiered and span several stores.
Non-conversion	An interaction that did not lead to a sale, classified by reason.
UPT / PA	Units per transaction (peças por atendimento) — the average number of items per sale.

Privacy and security

• Read-only. All nine tools only query data. None of them writes, changes or deletes information in PainelAlter.
• Same scope as the dashboard. The assistant sees exactly the stores you already see in PainelAlter — no more, no less. Changes to your dashboard access are reflected in the connector.
• Your own authentication. Sign-in happens on the PainelAlter screen (https://painelalter.com/mcp/authorize); your credentials are never given to the assistant.
• Revocation. To remove access, disconnect the connector in your assistant's settings. In Claude: Settings → Connectors.

TODO

Link AlterVision's privacy policy — there is no URL recorded in this repository.

Support

Questions, issues or suggestions about the connector: contact us via email at suporte@altervision.com.br.