Skip to main content

Connecting AI agents to admetrics using the Model Context Protocol (MCP)

A complete guide on how to configure and use the Admetrics MCP endpoint to run structured analytics queries directly via AI chat applications.

What you will learn in this article:

  • What the Model Context Protocol (MCP) is and how it functions within the Admetrics infrastructure.

  • How to configure AI chat applications - such as ChatGPT, Claude, Claude Code CLI, and Codex - to query Admetrics data.

  • How to run natural language analysis against your e-commerce performance data using pre-validated tools.

  • For full technical specifications and interactive query builder tools, visit our full reference documentation at https://developers.admetrics.io/docs/mcp.

Who this article is for

This article is designed for:

  • E-commerce Marketers & Media Buyers: Professionals who want to diagnose CAC spikes, MER drops, channel spend shifts, and daily metric changes using natural language chats instead of building manual reports.

  • Data Analysts & Growth Leads: Teams seeking automated performance diagnosis and quick metric breakdowns without writing manual HTTP queries.

  • Developers & Technical Teams: Integrators wanting to connect LLMs or automated agents directly to Admetrics Query Language (AQL) with validation guarantees before query execution.

What are the benefits

  • Direct AI Integration: Connect tools like ChatGPT, Claude, Claude Code, and Codex directly to catalog-backed analytics without writing custom HTTP backend code.

  • Zero-Code Natural Language Querying: Translate everyday performance questions into executable Admetrics Query Language (AQL) queries automatically.

  • Pre-Execution Tool Validation: The MCP endpoint exposes tools that allow AI agents to discover exact metric names, dimension structures, and client IDs prior to executing queries, minimizing query errors.

  • Flexible Authentication: Native support for OAuth sign-in across conversational chat apps, alongside managed API bearer tokens for command-line interfaces and server environments.

How to use it

To connect your AI application to Admetrics, use the central MCP endpoint URL:

https://api.admetrics.io/mcp

Setting up Claude:

  1. Open Settings in Claude and select Connectors.

  2. Click Add custom connector.

  3. Paste https://api.admetrics.io/mcp into the URL field and save.

  4. When prompted, complete the OAuth login to grant Claude access to your Admetrics workspace.

  5. Open a chat window, ensure the connector is active, and submit your prompt.

Setting up Claude Code (CLI):

1. Add the Admetrics MCP server via your terminal and sign in:

Bash

claude mcp add --transport http admetrics \  
https://api.admetrics.io/mcp

claude mcp login admetrics

2. Launch claude and begin querying your analytics - the Admetrics tools are available automatically.

Setting up ChatGPT:

Custom MCP connectors require a plan with custom connectors enabled, and ChatGPT's Developer Mode must be turned on before you can add one.

  1. Enable Developer Mode under Settings → Security & Login - without it, custom plugins cannot be added.

  2. Open Settings → Plugins → Browse plugins → Add plugin (or Settings → Connectors) and paste the MCP URL from above.

  3. Select OAuth as the authentication method and finish the sign-in.

  4. Enable the connector in a conversation and ask a question, for example: "Show my spend by channel for last week."

Setting up Codex:

1. Obtain a static API token from API Access and set it in your environment:

Bash

export AQL_BEARER_TOKEN="<your-token>"

2. Add the configuration entry to ~/.codex/config.toml:

[mcp_servers.admetrics]
url = "https://api.admetrics.io/mcp"
bearer_token_env_var = "AQL_BEARER_TOKEN"
tool_timeout_sec = 180

3. Start Codex and ask an analytics question.

Note: Regarding data privacy, customers retain full control over the data they transmit to third-party providers such as OpenAI or Anthropic, as this is controlled through explicit authorizations. The system itself does not perform any LLM processing of the data, but functions exclusively as an API interface.

Verifying your connection

To verify that your integration is active, ask your AI model: "List the analytics clients I can access."

A successful setup will trigger the client-listing tool and return your workspace accounts. If the request returns a 401 status code, re-authenticate via OAuth or verify your bearer token settings.

Requirements

  • An active Admetrics account with workspace access permissions.

  • A compatible AI chat interface (ChatGPT or Claude) or technical agent (Claude Code CLI or Codex).

  • User credentials to complete OAuth sign-in (or a valid token generated under API Access).

Practical examples and use cases

Once connected, your AI assistant can process complex analytical requests.


Use the prompt patterns below as templates:

Daily pulse and change diagnosis

  • "What changed yesterday vs 7-day avg for Spend, CAC, MER, NC ROAS, CVR, AOV, Revenue, Profit?"

  • "Why did CAC spike yesterday vs last week’s same weekday? Break down channel -> campaign -> ad set."

  • "Why did MER drop this week vs last week? Decompose CPM/CTR/CVR/AOV + mix shift."

  • "Show the top 10 drivers of the CAC increase this week vs last week."

Performance drivers and attribution shift

  • "Which campaigns drove the change in New Customers this week?"

  • "Where did spend shift this week vs last week (by channel + top campaigns)?"

  • "Which products/SKUs drove revenue change this week vs last week?"

Data reconciliation and health checks

  • "Is this change real or data lag? Show freshness/reconciliation for yesterday and today."

  • "What are today’s red flags vs baseline? List metrics outside bounds and likely causes."

Executive summaries

  • "Give me a weekly exec summary: what happened, why, and what we should do."

Note: Copy and paste these prompts directly into your configured AI chat session to initiate automated diagnostic workflows.

Additional resources and related articles

Frequently asked questions

Q: When should I use MCP instead of the standard REST API?

A: Use MCP when integrating conversational AI assistants or coding tools (like ChatGPT, Claude, or Codex) that need to dynamically discover metrics and execute queries using natural language. Use the REST API when building backend services, recurring data pipelines, or fixed applications that require static HTTP code contracts.

Q: How do I resolve a 401 unauthorized error during connection testing?

A: A 401 error indicates an expired or missing authentication token. Disconnect the connector inside your client's settings, re-add https://api.admetrics.io/mcp, and complete the OAuth sign-in flow again. For static command-line clients, confirm that your bearer API token is active and properly exported in your environment variables.

Q: Can an AI assistant modify my Admetrics workspace data via MCP?

A: No. The MCP endpoint exposes validated analytics query tools. The agent can only discover definitions and execute read-only queries based on the scope and permissions of your authenticated user account.

How to share feedback

If you have questions regarding MCP configuration, encounter issues with your client setup, or would like to submit new prompt templates for performance marketing use cases, please contact our support team via the chat widget through the Admetrics Help Portal or reach out directly to [email protected].

Did this answer your question?