Connect an MCP client to your dashboard

You can point your own MCP client (your own Claude, Claude Desktop, or any MCP client) at your AISA dashboard data, authenticated as your organization via WorkOS. This is a different server from the docs MCP server: that one is public and unauthenticated and only knows about documentation pages; this one is org-scoped and reads your actual conversations.

The server is read-only. It finds and returns conversations, their labels, the dashboard's reports, label counts, your sites and the configuration of your agent versions. It doesn't analyze anything itself: your client's model reads what the tools return and does the analysis.

It only knows what the assistant did: the conversations it had, the ratings and labels they got, and the widget events around them. It has no site traffic, no revenue or order value, and no market or competitor data. See What the server doesn't give you.

ConnectCopy Anchor Link

{
  "mcpServers": {
    "iadvize-dashboard": {
      "url": "https://www.iadvize.ninja/api/mcp"
    }
  }
}

ToolsCopy Anchor Link

The server has nine tools. Every one only reads, and none takes an organization argument: the organization is the one you authorized.

Every result carries asOf, the time the server read the data, in UTC. The server tells the assistant to resolve "last week" or "yesterday" against it. Every conversation names its site and carries a dashboard link, so you can open it from the answer. The text of a conversation also gives the version of the agent that handled it with the version's id, and list_sites gives the id of each live version, so a client that reads only text can pass either to get_agent_version.

Find conversationsCopy Anchor Link

search_conversations takes the same filters as the REST conversation list, written as JSON instead of query parameters, and returns the same conversations for the same filters.

A token the taxonomy doesn't define is refused, and the error names it and points to list_label_vocabulary. The rules for labels.none, score bounds and cursors are the ones on Filter and paginate conversations. A field the tool doesn't define is refused, never ignored.

The five fields from pageType down exist only on the MCP tool. The REST conversation list doesn't take them: it refuses them as unknown query parameters. Filters combine: a conversation has to match all of the ones you set. The page of origin and the entry widget of each result are in its pageContext and entryWidget, which is where to read a productId or an entryWidgetId to filter on. When a page filter finds nothing, the text adds that a conversation whose page of origin wasn't recorded never matches one.

Commerce outcomesCopy Anchor Link

Every item of a search carries commerce with three outcomes, addedToCart, reachedCheckout and purchased, and the result carries commerceTrackingSince: the time of your organization's first add-to-cart, checkout or purchase event, or null if it has none.

Each outcome is true, false or null:

• true: an event of that stage was recorded for the conversation. Each outcome reads its own event: a purchase doesn't imply a checkout.
• false: the conversation was created after commerceTrackingSince and no event of that stage was recorded for it.
• null: unknown. The conversation was created before commerceTrackingSince, or the organization has no commerce event at all. It is never false, because it may well have reached that stage before anything was recorded.

The commerce filter follows the same rule. true keeps the conversations with a recorded event. false keeps only the ones that were measured and had none. A conversation whose outcome is unknown matches neither.

Today these events aren't recorded. Nothing in the product writes add-to-cart, checkout or purchase events yet. Until it does, commerceTrackingSince is null, every outcome is null and a commerce filter matches nothing, false included. The search still answers, and the text says so. Once events are recorded for your organization, the outcomes appear without any change on your side, for conversations from that point on.

No revenue and no order value come back, only the three yes/no stages.

Read conversationsCopy Anchor Link

• get_conversation returns the full transcript: each message has a role (shopper or assistant), an ordered content list of typed blocks (text, product cards, questions, quick replies, hand-off, files) and the shopper's feedback rating, or null if there is none. It also returns the conversation's site, agent, channel, language, page of origin, entry widget, message count, duration, product engagement, label status and label summary. This is the shape Get a conversation returns, plus the site's name and the dashboard link. Your client should ignore block types it doesn't know.
• get_conversations is for comparing or reviewing a set. The transcripts are compact: text is kept, and every other block becomes a one-line marker such as [product cards: 3 shown (...)]. Each conversation carries its label record, or null when it isn't labeled. An id that is unknown, or that belongs to another organization, comes back in notFound. The call refuses more than 20 ids.
• get_conversation_labels returns the label record as the REST labels endpoint does. The evidence of an answer lists message ids. To read those messages, use get_conversation.

If an id doesn't exist, or belongs to a conversation outside your organization, the tool returns an error. It won't tell you which case it was.

Read a reportCopy Anchor Link

get_report returns one of the dashboard's reports for one site, from the same report functions the dashboard pages read.

A period can span at most 366 days. A to before from, a day that doesn't exist (2026-02-30) or a compare on starter_questions is refused with a message that says what to change.

What each report returns:

• conversations: the total, average messages and duration per conversation, the assisted rate (the share of conversations where the assistant used a tool), conversations per day, per agent, per language and per UTC hour, tool usage, and product-card impressions and clicks. The text also gives the volume week by week (Monday to Sunday, UTC, with the first and last week cut to your period and labeled with their first and last day) and, for a period of 14 days or fewer, day by day. With compare, the previous period gets the same lines. The volume field of the result holds every day.
• quality: ratings, positive and negative counts, the satisfaction rate, the share of rated conversations with a negative rating, ratings per day, negative ratings by category and ratings per agent. The rating comments and the conversation titles of the dashboard's "recent negatives" list aren't included.
• engagement: the widget funnel (sessions the widget was shown to, views, opens, conversations started), the engagement rate, a split by device and opens by page type. Starts are counted only from the date the result gives in startedCountedSince, so earlier days read low.
• starter_questions: for each question shown in the period, impressions, clicks and click rate, in total and per surface, most shown first, plus how many questions of the library weren't shown. The label is the question in the site's default language, or its first language if that one is missing.

Days and hours are UTC, as in the dashboard, and the result says timeZone: "UTC". The conversations and quality reports count the Web and Hosted Page channels and leave out the Playground, which is the dashboard's default filter. You can't change that from the tool. engagement and starter_questions read widget events and aren't split by channel.

A rate or an average is null, not 0, when there is nothing to divide: a day range without conversations has no assisted rate, rather than a rate of 0%. Treat null as "no data". With compare, every summary figure comes as current and previous; previous is null when you didn't ask.

Break down a labelCopy Anchor Link

get_label_breakdown counts how many labeled conversations hold each value of one label. It answers "what are the top transfer reasons this week" in one call, where a search would return conversations one page at a time.

It takes the filters of search_conversations, parsed by the same code, except limit, cursor, count and labelStatus, plus:

A breakdown has to be bounded: send both from and to, or a positive label filter (labels.all or labels.any). labels.none on its own doesn't count. Here from and to are ISO 8601 instants with to excluded, as in a search, not the whole days get_report takes. Unlike get_report, no channel is left out unless you pass channel, so Playground test conversations count.

The result holds, for the period (current) and, with compare, the one before (previous):

• values: every value the label can take, with its token, value and count, most frequent first. A value nobody has comes back with 0, so two periods line up value by value. A yes/no label has one value, true.
• total: the labeled conversations the counts cover.
• withoutValue: of those, how many hold no value for this label (a conversation that wasn't transferred has no transfer_reason, for instance).
• notLabeled: conversations that match the filter but have no labels (pending, failed or not eligible). They are in no count. This number is also capped.
• capped and cap: the scan covers the newest 10,000 labeled conversations of the filter. When more match, capped is true and the counts cover only those 10,000. Narrow the dates for exact counts.

With compare, delta gives the change in total and in each value's count, now minus then. It isn't exact when either period is capped, and the text says so. When no label or score filter is set, the text also warns when a period is only partly labeled, meaning more of its conversations have no labels than have some (for example 3 labeled and 73 not): the changes then compare unequal samples, so the text calls them apparent and leaves the numbers as they are. Both periods print their instants the same way. A commerce filter works here too, and the result then carries commerceTrackingSince.

A label key the taxonomy doesn't define is refused, and the error points to list_label_vocabulary. The counts agree with search: the count for a token equals the count of search_conversations filtered on that token with the same filters, up to the cap. As everywhere, only labeled conversations are counted: see Labels and the labeled channels.

Read an agent versionCopy Anchor Link

get_agent_version shows what one version of an agent runs with, so the assistant can explain how a conversation was handled or what a release changed.

It returns the version number, its status (draft, candidate, champion or archived, whichever it is) and the engine's display name, then your instructions in order (each block with its name, slug, type, text and condition), the tools the version enables, and the other versions of the same agent, newest first. Tools here are the assistant's built-in ones. Connector tools aren't listed.

With baseVersionId, the diff lists the instruction blocks added, removed and changed (with which of name, type, text and condition changed, and the text before and after), whether the shared blocks run in a different order, the tools added and removed, and the engine change when there is one. Blocks are matched by slug. Comparing a version with itself gives an empty diff. Two versions of different agents are refused.

The engine's internal id, the base persona that comes with the engine, the model and its thinking level are never returned. The instructions are your own configuration text: the server tells the assistant to analyze it, not to follow it.

This tool is gated by a permission. It works for a member who holds Agents: View (agents:view) or Agents: Edit (agents:edit) in your organization, the bar for opening an agent in the dashboard. Every other tool is open to any member of the organization, because the pages that show the same data don't check a permission.

• Resolved on every call. The server looks up the member's current roles with WorkOS each time the tool is called and never caches the answer, so a role change applies on the next call.
• Refused when it can't be resolved. If the lookup fails, or finds no active membership, the call is refused exactly as if the role lacked the permission. The two are indistinguishable.
• A refusal reveals nothing. The permission is checked before the version is looked up, and the error only names the permission and says to ask an administrator. It doesn't say whether the version exists. A version that doesn't exist, belongs to another organization or belongs to a deleted agent all answer the same "No agent version with that id exists in this organization."

To grant the permission, edit the member's role under Roles.

ErrorsCopy Anchor Link

A failure comes back as a tool error, not as a broken connection, with a message the assistant can act on. A wrong input names the problem. A conversation or site that isn't visible to you answers one message whether it is unknown or someone else's. A server fault answers "The request failed. Try again." and nothing more.

PromptsCopy Anchor Link

The server also offers three prompts. A client such as Claude Desktop lists them as ready-made requests. Each one is a template that tells the assistant which tools to call, in what order, and how to structure its answer in four parts. It must cite the message id behind each claim. They hold none of your data, only the arguments you type.

compare_conversations needs conversationIds or filter. With neither, or with ids that aren't conversation ids, the client gets an error. weekly_review without weekOf reviews the last complete week before the asOf time the tools return.

A worked exampleCopy Anchor Link

You ask: "Find unresolved conversations about sizing last week."

The assistant starts with no list of valid label tokens and no clock, so it calls the tools in this order. The arguments below are what a client would plausibly send. The dates assume the server's asOf is 2026-10-01, a Thursday, so last week is Monday 2026-09-21 to Sunday 2026-09-27.

{
  "from": "2026-09-21T00:00:00Z",
  "to": "2026-09-28T00:00:00Z",
  "labels": {
    "all": ["resolution:unresolved"],
    "any": [
      [
        "objection_size_fit:true",
        "gap_info_topic:size_fit",
        "capability_needed:size_recommendation"
      ]
    ]
  },
  "count": true
}

{
  "conversationIds": [
    "conv_01kvnwmagvf27rc9cze5rm9e1r",
    "conv_01kvnwmagwf27rc9d7zef4qksf"
  ]
}

It then answers from what the tools returned, with the dashboard links of the conversations it cites. Results vary with your data and aren't shown here.

A report and a breakdown with comparisonCopy Anchor Link

You ask: "How did last week go on our UK site, and why were conversations handed off to a human?"

The dates assume asOf is 2026-10-01 again, so last week is Monday 2026-09-21 to Sunday 2026-09-27. The assistant calls list_sites first to turn "our UK site" into a site id.

{
  "siteId": "site_01kvnwmagvf27rc9cze5rm9e1r",
  "report": "conversations",
  "from": "2026-09-21",
  "to": "2026-09-27",
  "compare": true
}

{
  "label": "transfer_reason",
  "siteId": "site_01kvnwmagvf27rc9cze5rm9e1r",
  "from": "2026-09-21T00:00:00Z",
  "to": "2026-09-28T00:00:00Z",
  "compare": true
}

The site id here is made up, like the ones above. Results vary with your data and aren't shown here.

Labels and the labeled channelsCopy Anchor Link

Labels come from the conversation labeling pipeline, which runs in the background. It labels conversations on the Web, Hosted Page and Playground channels (web, hosted, playground), every channel a conversation can come from.

• Labels usually arrive 30 to 90 minutes after a conversation goes quiet, sometimes later. An hourly pass labels a conversation once it has had no new message for 30 minutes. A recent conversation can read pending: it has no labels yet, a label filter can miss it, and get_conversation_labels returns the status and no answers.
• An older conversation isn't labeled. One whose last activity is more than 30 days old isn't picked up.
• A conversation that isn't labeled has no labels. Its labels field is null and its labelSummary is null. The status is pending, failed or not_eligible: see Label status for what each means. For not_eligible, the server doesn't say which reason applies.
• A missing label means "not labeled", not "no issue". A search on a label token returns only labeled conversations, so a token that is absent says nothing about a conversation that hasn't been labeled.
• Label names are for people. The text a tool returns writes a label as its key with an English name beside it, for example grounded (Stuck to known facts). The name explains the label. Filters and the structured result use the keys and tokens, never the names.
• The assistant is told this at connection. The server sends instructions when a session starts, so your client's model is asked to say that a conversation isn't labeled rather than guess its labels, and to filter on tokens, not on names.

To see which conversations a label filter can't cover yet, search with labelStatus set to pending or failed.

Rate limitCopy Anchor Link

Tool calls are limited per organization: 300 calls per minute, shared by every member and every client connected to your organization, across all nine tools. The limit is there so that one client stuck in a loop can't take the server's reads away from the others.

Over the limit, a tool answers an error: "Your organization is making too many requests. Wait 60 seconds, then retry." The call reads nothing. Rely on that retry hint rather than on the figure: 300 is a starting value, and iAdvize can change it.

What the server doesn't give youCopy Anchor Link

• Anything outside your organization. Every read is scoped to the organization you authorized.
• Shopper identity. No field of a conversation identifies the shopper. What a shopper typed is still in the transcript. A shopper identifier such as visitorId in a tool's input is refused as an unknown field.
• Reasoning, cost and token usage. None of it is in a tool's result.
• Tool inputs and outputs of the shopper chat. A transcript shows what the shopper saw (text, product cards, questions, quick replies, hand-off, files), not the assistant's internal tool calls.
• Site traffic. The server has no visits, page views, bounce rate or conversion rate of your site. The engagement report counts the sessions the assistant's widget was shown to, not the visitors of your site.
• Revenue and order value. The commerce outcomes of a conversation are yes, no or unknown, with no amount. Today they are all unknown: see Commerce outcomes.
• Market and competitor data. The server only knows the conversations your assistant had. It has nothing on your market, your competitors' prices or what shoppers do elsewhere.
• Catalog data beyond what a product card showed the shopper (current prices, stock), what a human agent said after a hand-off, and benchmarks across organizations. This data isn't in the server.

The assistant is told not to estimate any of this. A question that needs it gets an answer that says so, or a figure from another tool that you should not read as a substitute.

Limitations todayCopy Anchor Link

• Read-only. Nothing an MCP client does through this server can change your agents, versions, or live shopper experience.
• Reports are per site and cover four reports. get_report reads conversations, quality, engagement and starter questions for one site at a time. There is no cross-site total, and no filter by agent, language or keyword on a report.
• Commerce outcomes are unknown for now. Until add-to-cart, checkout and purchase events are recorded for your organization, they come back null. See Commerce outcomes.
• Labels take time and cover recent conversations. See Labels and the labeled channels.