MCP reference

Maya Insights exposes marketing analytics to AI assistants through a hosted Model Context Protocol server. This page is the protocol contract: the endpoint, how authorization works, and the tools an assistant can call.

:::tip Just want to connect Claude? Follow Connect Claude instead — it is three clicks and no configuration. This page is for connecting an assistant other than Claude, or for understanding what an assistant is doing on your behalf. :::

Endpoint

https://mcp.mayainsights.com/mcp

Transport is Streamable HTTP. The endpoint is the same for every user; authorization determines which organization's data is reachable.

Authentication

OAuth 2.0 authorization code with PKCE (S256) and dynamic client registration. Clients are public — there is no client secret.

Discovery starts at the protected-resource metadata:

https://mcp.mayainsights.com/.well-known/oauth-protected-resource

That document names the authorization server, which in turn advertises its authorize, token, registration, and JWKS endpoints. An unauthenticated request to the MCP endpoint returns 401 with a WWW-Authenticate header carrying resource_metadata_uri, so a compliant client can discover the flow without prior configuration.

Access is per user, scoped to the organizations that user belongs to. Access tokens are short-lived and refreshed automatically; a session lasts 30 days. Complete the OAuth flow — never ask a user to paste a credential.

Tools

Tool	Purpose
snapshot	Entry point for an analytics question. Takes the question in natural language, selects and runs the appropriate analysis, and returns a rendered result. That result is the deliverable.
get_analysis_category	Lists the analysis categories the authenticated organization actually has.
get_glossary	Describes the queryable data within a category, in the organization's own terms.
get_data	Runs a parameterized query against a category. Call get_glossary first.
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.
list_feedback	Lists feedback the user has already submitted.

Every tool is read-only.

Call order

1. An analytics question goes to snapshot. Use what it returns directly — no follow-up routing call is needed.
2. If snapshot reports that no category matched, call get_analysis_category, let the user choose, and continue with that category.
3. For numbers a packaged analysis does not return, call get_glossary and then get_data.
4. To explain a term, call get_field_details.

Before calling submit_feedback, show the user the draft and get explicit confirmation. Never submit something they have not seen.

Discovering capability at runtime

Do not assume a fixed set of categories. What is available depends on the sources an organization has connected and on its subscription. get_analysis_category is the source of truth, per session.

If every tool errors simultaneously, the connection has dropped rather than the request being invalid. Prompt the user to reconnect Maya Insights from their account settings.

Machine-readable summary

A condensed version of this contract, intended for agents, is at /llms.txt.