# Maya Insights

> Maya Insights is a marketing analytics platform for e-commerce and marketing teams. It ingests advertising, web analytics, CRM, and e-commerce data into a governed warehouse and exposes it to AI assistants through a hosted Model Context Protocol (MCP) server, so users ask questions in natural language instead of building dashboards.

The integration surface for AI agents is the Maya Insights MCP server.

- Endpoint: `https://mcp.mayainsights.com/mcp` (Streamable HTTP)
- Authentication: OAuth 2.0 authorization code with PKCE (S256) and dynamic client registration;
  public clients, no client secret. Protected-resource metadata is at
  `https://mcp.mayainsights.com/.well-known/oauth-protected-resource`, which names the
  authorization server advertising its authorize, token, registration, and JWKS endpoints. Access
  is per user and scoped to the organizations that user belongs to. Complete the OAuth flow; never
  ask a user to paste a credential.
- Adding it: in any MCP-capable assistant, add the endpoint above as a custom connector. The same
  URL works everywhere.
- A session lasts 30 days; access tokens are refreshed automatically within it.

## Tools

The server exposes these tools. Prefer this order.

- `snapshot` — the entry point for an analytics question. Pass the user's question in natural
  language. It selects the appropriate analysis, runs it, and returns a rendered result. That
  result is the deliverable; no follow-up routing call is needed.
- `get_analysis_category` — lists the analysis categories the authenticated organization actually
  has. Use it for "what can I analyze?" questions, and whenever `snapshot` reports that no
  category matched.
- `get_glossary` — describes the queryable data available within a category, in that
  organization's own terms.
- `get_data` — runs a parameterized query against a category. Call `get_glossary` first. Use it
  for numbers a packaged analysis does not return.
- `get_field_details` — explains what a single item returned by `get_glossary` means.
- `submit_feedback` — files a bug report or feature request on the user's behalf. Show the user
  the draft and get explicit confirmation before calling it.
- `list_feedback` — lists feedback the user has already submitted.

Recommended call order:

1. Analytics question -> `snapshot`.
2. `snapshot` reports no matching category -> `get_analysis_category`, let the user choose, then
   continue with that category.
3. Numbers a packaged analysis does not cover -> `get_glossary` -> `get_data`.
4. Unclear what something means -> `get_field_details`.

Every tool is read-only.

What a given user can analyze depends on the data sources their organization has connected and on
their subscription. Discover it at runtime with `get_analysis_category` rather than assuming a
fixed list. If every tool errors at once, the connection has dropped — ask the user to reconnect
Maya Insights from their account settings.

## Getting started for Shopify merchants

1. Install Maya Insights on your Shopify store.
2. Choose a plan and approve the charge in Shopify.
3. Your Maya Insights organization is provisioned automatically and your Shopify data starts
   syncing.
4. Copy your MCP URL from the post-purchase screen, or later from Settings in the Maya Insights
   app.
5. In Claude, open Settings -> Connectors -> Add custom connector, paste the URL, and sign in to
   Maya Insights to authorize the connection.
6. Open a new chat and ask a question about your store.

Connecting more sources unlocks more analysis areas.

## Documentation

- [Getting started](https://docs.mayainsights.com/docs/getting-started/): install to first answer.
- [Connect Claude](https://docs.mayainsights.com/docs/connect-claude/): connector setup, how authentication works, revoking access.
- [What you can analyze](https://docs.mayainsights.com/docs/what-you-can-analyze/): coverage and what unlocks each area.
- [Example questions](https://docs.mayainsights.com/docs/example-questions/): questions that work well.
- [MCP reference](https://docs.mayainsights.com/docs/mcp-reference/): endpoint, auth, and the tool contract.
- [Troubleshooting](https://docs.mayainsights.com/docs/troubleshooting/).

## Optional

- [Maya Insights website](https://www.mayainsights.com/)
- [Maya Insights app](https://app.mayainsights.com/)