SparkX AI MCP User Guide
Connect SparkX AI advertising data to your AI assistant for natural-language queries, analysis, and custom workflows.
SparkX AI MCP connects advertising data from the SparkX AI platform to the AI assistant you already use. After setup, you can use natural language to query ad performance, entity configuration, and operation logs. You can also ask AI to combine SparkX AI data with your own cost, gross margin, targets, or other business context for analysis.
The current version mainly supports data queries and analysis. It does not support directly creating, modifying, enabling, or pausing advertising entities from your AI assistant.
1. What Is MCP
MCP, or Model Context Protocol, is a standard protocol that allows AI assistants to connect to external systems. You can think of it as a standard way for AI assistants to access business systems.
Compared with an API, an API is more like an interface for systems or developers. To connect a system through APIs, engineers usually need to read API documentation, write code, handle authentication, and map fields. MCP builds on top of API capabilities and provides a more standardized connection method for AI assistants.
SparkX AI packages platform data retrieval capabilities as MCP Tools, and AI assistants call these Tools through the MCP protocol. This means you do not need to write code or remember every API and field name. You can ask questions in natural language and let AI query and analyze the data.
In one sentence:
MCP is the USB-C of the AI world. We turn SparkX AI advertising capabilities into a standard connector, so your AI can plug in and use them.
2. What SparkX AI MCP Can Do
After setup, you can use SparkX AI MCP in an AI assistant that supports MCP to:
Query advertising data in natural language: for example, "Sort last week's campaigns by ACOS from highest to lowest" or "What is the TACOS trend for this product line over the last 8 weeks?"
Analyze with your own business data: for example, provide product cost, gross margin rate, inventory pressure, or target ACOS, and ask AI to identify which campaigns need adjustment based on SparkX AI advertising data.
Reuse fixed analysis workflows: for example, turn recurring tasks such as weekly ad reports, monthly reports, product diagnosis, or ad structure analysis into Skills, reducing the need to describe the same analysis method every time.
Trace human and AI operation records: for example, review recent changes to budget, bids, targeting, or managed groups for a specific campaign.
Manage AI managed groups (requires write permission): create, edit, and delete managed groups in your AI assistant, and adjust target ACOS, managed goals, AI status, action spaces, and campaign bindings under each managed group.
3. What You Can Do: Query + Manage
SparkX AI MCP currently supports querying three types of data and managing AI managed groups.
3.1 Reporting and Performance Data
This includes advertising performance metrics and selected business metrics, such as:
Impressions, clicks, spend, sales, orders, units sold
ACOS, ROAS, click-through rate (CTR), conversion rate (CVR), cost per click (CPC), cost per order
AI-managed sales, ACOS, and ROAS
ASIN-level total sales, TACOS, sessions, page views, Buy Box ownership, and more
3.2 Entity Configuration and Metadata
This includes key advertising objects and configuration in the ad account, such as:
Campaigns, ad groups, targeting, and advertised products
ASIN title, inventory, advertising eligibility, and other product information
Managed groups, product lines, and other grouping information
3.3 Operation Logs
This includes operation records from both users and AI, such as:
Changes to campaigns, ad groups, targeting, bids, budgets, and managed groups
Operator, action type, entity, and operation time
AI-managed operations and related performance changes
3.4 AI Managed Group Management
This includes creating, editing, and deleting AI managed groups, such as:
Create AI managed groups
Adjust target ACOS, managed goals, AI persona, and AI switch
Configure action spaces (AI/RBA)
Add or remove campaigns under a managed group
4. Before You Start
Before using SparkX AI MCP, make sure you have:
A SparkX AI platform account with access to the stores or ad accounts you need to query.
An AI assistant that supports MCP, such as WorkBuddy, Claude, ChatGPT Codex, Cherry Studio, or Coze.
5. How to Set Up SparkX AI MCP
Choose an authorization method and connect MCP. OAuth is recommended, and MCP Token is also supported.
Install Skills and verify the connection. Confirm that AI can call the tools correctly and read the authorized scope.
Start using it. Query, analyze, and execute authorized operations in natural language.
Option A: OAuth Authorization
OAuth is suitable for clients that support this authorization method. You do not need to create, copy, or store an MCP Token. When connecting, sign in to SparkX AI and confirm the authorization.
One-prompt setup: in clients where AI can configure MCP by itself, such as Claude, ChatGPT Codex, Cherry Studio, Coze, or WorkBuddy, send the following prompt directly:
Please read the following GitHub repository and follow its instructions to configure SparkX AI MCP and install the Skills: https://github.com/SparkXAI/MCP When authorization is required, open the sign-in page so I can complete the authorization. After the configuration is complete, call get_user_authorized_context to verify the connection.
When the client prompts you to sign in or authorize, open the authorization page, sign in to SparkX AI, and confirm the connection.
After authorization is complete, return to the AI client.
Note: For customers in mainland China, use Claude, especially personal Claude accounts, with caution when connecting to SparkX MCP. Due to Anthropic's regional policies, there is some uncertainty when using Claude from mainland China, and there is a chance the account may be flagged or restricted. We recommend WorkBuddy or Codex for mainland China customers.
Option B: Create a Token on the Platform
Log in to the SparkX AI platform and go to the MCP & Skill page.
Click Create Token, select the required authorization scope, and create the Token.
Copy the generated Token and keep it in a secure place.
Note: You usually cannot view the Token again after leaving the page. If you did not save it, create a new one.
4. Configure MCP in your AI assistant
We recommend using the one-prompt setup method. Open an AI assistant that supports MCP and send the following prompt:
Please read this GitHub repository and follow the instructions to configure SparkX AI MCP and install the Skills: https://github.com/SparkXAI/MCP Token: <paste your Token> After setup, call get_user_authorized_context to verify the connection.
The AI assistant will configure MCP based on the repository instructions and call the verification tool. If it returns your user information and authorized store or Profile list, the setup is successful.
Option C: Manual Setup (Advanced)
If your AI assistant does not support automatic setup, add a remote service in the MCP settings.
MCP service URL:
https://mcp.sparkx.cn/mcp
Request header:
Authorization: Bearer <your Token>
Claude Code CLI example:
claude mcp add --transport http sparkx-mcp https://mcp.sparkx.cn/mcp --header "Authorization: Bearer <your Token>"
ChatGPT Codex example:
[mcp_servers.sparkx-mcp]
url = "https://mcp.sparkx.cn/mcp"
bearer_token_env_var = "SPARKX_TOKEN"
http_headers = {}
Different AI assistants may have different MCP settings. If you see a 401 error, the Token may be incorrect or missing permission. If the request times out, check your network connection and MCP configuration first.
6. How to Ask Questions
After setup, you can ask questions in natural language. For more accurate results, include:
Query object: store, campaign, ad group, ASIN, product line, managed group, etc.
Time range: yesterday, last week, last 30 days, a calendar month, etc.
Metrics: spend, sales, ACOS, ROAS, TACOS, orders, etc.
Output format: table, Top N list, trend summary, anomaly explanation, action recommendations, etc.
Common question scenarios include:
6.1 Account or Store Health Check
Use this for daily account checks or weekly performance reviews.
Review this store's advertising performance last week. Summarize the main changes in spend, sales, ACOS, and ROAS, and point out the most important anomalies.
Compare the last 7 days with the previous 7 days. Which campaigns had the fastest spend increase? Did the increase bring sales growth?
6.2 Campaign or ASIN Diagnosis
Use this to diagnose a specific campaign, product, or product line.
Diagnose this ASIN's advertising performance over the last 30 days, focusing on spend, sales, ACOS, conversion rate, and inventory-related risks.
List campaigns from the last 14 days with ACOS above target and high spend, and provide prioritized recommendations.
6.3 Search Term and Targeting Analysis
Use this to find wasted spend, promising search terms, or targeting that needs adjustment.
Find search terms from the last 30 days with high spend and no orders, sorted by spend.
Which search terms had high ROAS but limited impressions or budget in the last 14 days? Provide a list of candidates for scaling.
6.4 Product Line or Ad Structure Analysis
Use this to check whether ad resources are allocated reasonably.
Summarize ad spend, sales, ACOS, and TACOS by product line for the last 30 days, and identify which product lines are over- or under-allocated.
Analyze my ad structure by ad type and match type. Break down spend and output, and identify structural imbalance.
6.5 Operation Log Tracing
Use this to understand whether performance changes are related to human or AI operations.
ACOS increased for this campaign over the last 14 days. Check the related budget, bid, and targeting operation logs during the same period and identify possible causes.
List the main operations AI performed on managed groups in the last 7 days, and explain whether key metrics changed after those operations.
6.6 Analyze with Your Own Data
If you have your own cost, gross margin, inventory, or target data, provide it in the conversation and ask AI to analyze it together with SparkX AI data.
Here are my product costs and target gross margin rates. Combine them with ad spend and sales from the last 30 days, identify ASINs with poor actual profit performance, and provide adjustment recommendations.
The target TACOS for this product line this month is 12%. Based on current ad performance and total sales, should we control budget or increase investment?
6.7 Weekly Reports, Monthly Reports, and Fixed Templates
If you need the same analysis framework on a regular basis, use a Skill or a fixed prompt.
Generate last week's advertising report, including core KPIs, week-over-week changes, abnormal campaigns, Top movers, and recommendations for next week.
Generate last month's advertising report, including MoM and YoY comparison, ad structure, product performance, keyword performance, and target achievement.
7. Use Skill Hub
A Skill is a reusable set of analysis instructions. After a Skill is installed, the AI assistant follows fixed steps to query data, analyze it, and produce output for the matching scenario.
7.1 Official Skills
Common official Skills include:
Skill | Use case | Output |
Weekly Ad Report | Weekly advertising performance review | KPI week-over-week changes, 7-day trends, anomalies, Top lists, and recommendations for next week |
Monthly Ad Report | Monthly business review | MoM and YoY comparison, ad group structure, product and keyword performance, and target achievement |
Ad Structure Analysis | Budget and traffic structure review | Spend and output breakdown by ad type and targeting method, with structural imbalance diagnosis |
Product Diagnosis | ASIN performance troubleshooting | ASIN ranking layers, low-performing product identification, variation comparison, inventory and advertising eligibility checks |
7.2 Install Skills
In most cases, when you configure SparkX AI MCP by following the GitHub repository instructions, the AI assistant will install the required official Skills for you. After setup, you can ask the AI assistant to confirm the list of installed Skills.
If the AI assistant does not install them automatically, or if your client requires manual installation, tell the AI assistant which Skill you want to use. For example:
I want to install the Weekly Ad Report Skill.
Or:
Help me install the official Skills for SparkX AI MCP.
The AI assistant will guide you through the installation. After installation, you can say "Generate last week's advertising report" or "Help me run a product diagnosis." If the AI assistant asks you to upload or select a Skill file, follow the instructions in your client.
7.3 Create Your Own Skill
If your team has a fixed analysis method, you can turn it into a custom Skill. We recommend defining:
Use case: weekly review, target achievement check, product line budget review
Data needed: campaigns, ASINs, search terms, operation logs
Analysis steps: overview, anomalies, causes, recommendations
Output format: table, summary, action item list
8. FAQ
Q1: How Does SparkX MCP Access, Process, and Protect Customer Data?
Within the scope authorized by the customer, SparkX MCP enables MCP-compatible AI clients such as Claude, Codex, and Cursor to query SparkX data. The following sections explain how SparkX MCP accesses and processes that data.
Access Scope
Connecting MCP does not give an AI client access to the entire SparkX account. Every request is subject to SparkX identity and permission checks. The accessible scope is determined by the intersection of the current user's permissions, the MCP Token permissions, and the authorized Profiles. An MCP Token cannot expand the user's existing data permissions.
SparkX MCP can provide data retrieval and advertising operation capabilities, depending on the tools currently available and the permissions granted to the MCP Token. Read and write permissions are controlled separately. Without the relevant write permission, MCP cannot modify an advertising account. For a request that may change a campaign, budget, bid, or other configuration, the client must display the proposed action and execute it only after receiving explicit confirmation from the user.
Data Processing Flow
The AI client sends the parameters and call information required for a request to SparkX only when it invokes a SparkX MCP tool. After completing permission checks, SparkX performs the authorized data query or advertising operation and returns the result to the client. Connecting MCP does not initiate a full data sync or automatically perform advertising actions. SparkX also does not automatically receive the user's entire conversation with the AI client simply because MCP is connected.
Data Processing by Third-Party AI Services
After a tool result is returned to the AI client, the customer's selected AI client and model provider continue processing it. Whether the provider stores the data, how long it retains the data, and whether it uses the data for product improvement or model training depend on the provider's product tier, contract, privacy policy, and account settings. SparkX does not control these third-party practices.
Enterprise customers should use AI services and enterprise accounts approved by their internal security and legal teams. They should also configure data retention, model improvement, and data-sharing settings according to their own data governance requirements.
Token Security
An MCP Token identifies the user and authorizes access. Manage it with the same level of security as a password or API Key. Do not include a Token in a chat, document, or support ticket, and do not share a personal Token with other people. If a Token is exposed or no longer needed, disable or delete it in SparkX immediately.
Q2: Why can't AI find data after setup?
First, ask AI to call get_user_authorized_context to verify authorization. If it cannot return authorized stores or Profiles, check whether the Token is correct, expired, or missing the required store or ad account permission.
Q3: Why does AI give slightly different answers to the same question?
MCP provides queryable data. The final analysis is generated by the AI assistant. Different AI assistants, conversation context, and question wording may change how conclusions are organized. To improve consistency, specify the time range, object, metrics, and output format in your question.
Q4: When should I use MCP, and when should I use InsightAgent?
Use InsightAgent when you want ready-made analysis directly inside the SparkX AI platform. InsightAgent is better for out-of-the-box ad diagnosis, anomaly analysis, and platform-based reviews.
Use MCP when you want to query SparkX AI data in your own AI assistant, or when you need to combine it with your own cost, gross margin, inventory, targets, internal spreadsheets, or other context. MCP is better for follow-up questions, cross-source analysis, fixed report generation, and personalized workflows.
They are not replacements for each other. InsightAgent helps you get standard conclusions quickly inside the platform. MCP brings SparkX AI data into your own AI workflow for further analysis.
Q5: How is MCP different from viewing reports directly in SparkX AI?
Platform reports are better for fixed dashboards and standard metrics. MCP is better for natural-language queries, cross-source analysis, fixed report generation, and personalized follow-up questions in your own AI assistant. You can use both together.
9. Appendix: Common Metrics and Objects
You usually do not need to remember every field name. Natural-language descriptions are enough for daily use. The following reference is only for cases where you need to specify metrics or objects precisely.
9.1 Common Metrics
Category | Example metrics |
Traffic | Impressions, clicks, spend, AI spend |
Sales and conversions | Sales, orders, units sold, conversion rate |
Efficiency | ACOS, ROAS, click-through rate, CPC, cost per order |
New customer | New customer orders, new customer sales, new customer order share |
Detail page | Detail page views, detail page view rate |
AI management | AI-managed sales, AI-managed ACOS, AI-managed ROAS |
ASIN business | Total sales, TACOS, sessions, page views, Buy Box ownership |
9.2 Common Query Objects
Object | Common use |
Campaign | Review overall budget, spend, sales, and efficiency |
Ad group | Analyze structure and performance differences within campaigns |
Targeting | Analyze keyword, product targeting, or audience targeting performance |
Search term | Find high-converting terms, wasted spend, and new opportunities |
Advertised product | Review advertising performance of promoted ASINs |
ASIN | Analyze product health with both advertising and business metrics |
Managed group | Review AI-managed configuration, operations, and performance changes |
Product line | Review budget and sales contribution by business grouping |
9.3 Common Operation Log Filters
Filter | Examples |
Time range | Last 7 days, last week, a calendar month |
Operator | Manual operation, AI operation, specific user |
Operation object | Campaign, ad group, targeting, budget, bid, managed group |
Action type | Create, update, enable, pause, budget adjustment, bid adjustment |