Marxx MCP server documentation

Overview

Marxx is a creative intelligence platform for paid social. The Marxx MCP server lets an AI assistant work with the same data from inside a chat. The assistant can read a client's Meta and Google Ads performance, look at competitor ads, run audits, pull brand and audience knowledge, and, when a client has the matching switches on, draft ad changes, generate creative and edit video.

The server lists 100 tools in 11 sections. A connected user may see fewer, because some groups are off until they are switched on for that client. With default settings a client sees the groups that are on by default, up to 38 tools, and the Google Ads tools only when Google Ads is connected. See Tool access.

It works with Claude, ChatGPT, and any MCP client that supports remote servers with OAuth and Streamable HTTP. For the product overview and sample questions, see the Marxx MCP page.

Requirements

• A Marxx account with an active subscription or trial. An account that is still in onboarding cannot use the server.
• For a client's own numbers, the client's Meta ad account and, if you use them, Google Ads account connected in Marxx. Competitor and brand tools do not need an ad account.
• An assistant that can add a remote MCP server by URL and sign in with OAuth. On team and enterprise plans, a workspace owner may need to allow or add custom connectors first.

Connect

Claude

1. Open Customize, then Connectors, in Claude.
2. Choose Add custom connector.
3. Paste https://api.marxx.ai/mcp and add it.
4. Claude opens a Marxx sign-in and approval page. Sign in with your own Marxx account and choose Approve.

ChatGPT

1. In ChatGPT, open the settings where you add a custom connector or MCP server. The menu names change from time to time.
2. Set the server URL to https://api.marxx.ai/mcp.
3. Approve the authorization prompt on Marxx.

Other MCP clients take the same URL and the same approval flow. Marxx also shows the address inside the app under Settings, then Integrations. Step-by-step help with screenshots is in the help centre.

Authentication and permissions

• OAuth 2.1 with PKCE (S256). Clients register dynamically or with a client ID metadata document. They are public clients. There are no client secrets and no API keys to paste.
• Authorization server: https://mudra.marxx.ai. The consent screen is on app.marxx.ai. You sign in with your own Marxx account.
• Token lifetime. Access tokens last 15 minutes. Refresh tokens last 14 days and rotate every time they are used. Reusing an old refresh token revokes the whole chain.
• Scope: the server requires marxx.read. Access tokens are signed RS256 JWTs bound to the audience https://api.marxx.ai/mcp.
• Access is checked on every call. The server looks up your user, organisation and role in Marxx each time and caches nothing. Your user, organisation and role are looked up from Marxx on every call.
• Ad platform access comes from the Marxx workspace, not from the assistant. Meta is connected with Meta Business Login. The permissions Marxx requests are ads_management, ads_mcp_management, business_management, pages_show_list, pages_read_engagement, pages_manage_ads, pages_manage_metadata, leads_retrieval, instagram_basic, instagram_manage_insights and instagram_manage_comments. Google Ads uses the adwords scope.
• A permission is not an action. The Meta and Google permissions above are broader than reading. The MCP server writes to an ad account only through the draft and apply flow in Changing ads safely, and only when that client has the changes switch on.
• Disconnect. Remove the connector in your assistant to end that assistant's access. Disconnecting Meta or Google inside Marxx cuts ad-account access for every Marxx surface, the MCP server included.

Clients (workspaces)

Agencies and teams with several clients keep each client in its own Marxx workspace. The assistant works on one client at a time.

• If you have more than one client, the assistant calls marxx_select_workspace and asks which one you mean. Every other tool refuses until a client is picked.
• If you have one client, it is picked automatically.
• The choice is saved per user, so it applies to all of your connected assistants. Switch it the same way whenever you like.
• Tool switches below are set client by client, so two clients in the same account can have different tools available.

Tool access

Reading is on by default. Anything that changes an ad account, spends credits or edits a video sits in a group that is off until it is switched on for that client. Switches are set client by client in Marxx. Contact support to switch a group on.

A tool in a switched-off group is hidden from the assistant's tool list, and refuses if it is called anyway.

Tool reference

100 tools, grouped. The Access column says what a tool can do:

• Read
• Changes ad account
• Spends credits
• Writes to Marxx

Writes to Marxx means the tool saves something inside Marxx, such as a draft, a board or a project. It does not touch an ad account.

Changing ads safely

Changes to Meta and Google Ads are available only when that client has Meta ads changes or Google Ads changes switched on. Both are off by default. When they are on, a change goes through four steps.

1. Draft. The assistant calls a draft tool. Marxx runs a basic validation check with the ad platform before showing it, and stores it as a draft. A draft holds up to 50 changes.
2. Show. The assistant shows you exactly what would change.
3. Your yes. The assistant is instructed to wait for your yes to that exact draft before it applies anything. Approval happens in the conversation. Read the draft before you answer.
4. Apply. The assistant applies the draft. Each draft can be applied once, only by the same user for the same client, only while it is pending, and only within 30 minutes. A draft that has expired has to be drafted again.

High-risk changes

Some changes need a second, specific confirmation. The server refuses to apply them unless the assistant passes a high-risk confirmation, and the assistant is instructed to get your specific confirmation first. They are:

• Meta: turning things on, archiving, a budget move of more than 50 percent, targeting changes on a live ad set, new ads or ad sets created as active, and publishing a new campaign.
• Google Ads: removing anything (removals are permanent), turning things on, switching bidding strategy, large rises in budgets, bids or targets, and broad match combined with manual CPC.

What it will and will not do

• New Google campaigns and ad groups are created paused. New Google campaigns are Search only.
• A new Meta campaign is staged as a draft in the client's Meta Ads Manager at the moment it is drafted. Nothing runs until it is published, and publishing is its own high-risk change. Marxx cannot discard that draft for you: delete it in Meta Ads Manager.
• Meta copies are created paused. Media added to a draft is uploaded to the ad account's media library when the draft is made.
• Meta: nothing is deleted. Archive is the furthest a change can go. Google: removals are possible, permanent and always high-risk.
• Meta new campaigns support website and instant-form destinations, one ad set and Advantage+ placements, with objectives Traffic, Leads, Sales, Awareness and Engagement. WhatsApp, Messenger, app and catalog campaigns are not supported.
• Per draft: Meta new campaign up to 50 ads, new ads into an existing ad set up to 10, a campaign copy up to 10 ad sets and 50 ads. Google up to 200 keywords, 10 ad groups and 10 ads.
• There is no separate spend limit in the change tools. The ad platform's own limits and your confirmation are the controls.
• For Meta, if the campaign, ad set or ad changed after the draft was made, the apply sends nothing.
• The change history tools list what was drafted and what was applied.

Video editor

The editor works differently. Paid steps need a quote (valid for 15 minutes) and you pressing Approve in the open editor tab. Steps that cannot be undone, run through marxx_editor_destructive, also need Approve in the tab. Archiving a project uses a confirmation the assistant passes itself, with no Approve in the tab. An archived project can be restored.

Credits

• Data, audit, competitor, Meta and Google tools spend no Marxx credits. Live Google Ads reads use Google's API quota instead.
• Some creative generation tools spend Marxx credits. The tools marked Spends credits above are the ones that do. If you are unsure, ask the assistant to run marxx_estimate_cost or marxx_credit_balance.
• marxx_estimate_cost is free and prices a generation before it runs. The assistant is instructed to quote the cost and get your approval before spending. Check the number before you agree.
• Most generation tools accept a ceiling (1 to 100,000 credits) that stops a run from going over it. The avatar and UGC tools bill themselves and cannot be capped.
• Video editor: paid steps need a quote and your Approve in the editor tab. Through the MCP server there is a default daily cap of 2,000 credits per person, counted per UTC day.

Limits

• Rate limit: 60 requests per minute per token. Over the limit the server returns HTTP 429 with a Retry-After header.
• Changes: up to 50 per draft, drafts expire after 30 minutes, and the per-campaign limits are listed under Changing ads safely.
• Meta media upload: images up to 30 MB, videos up to 1 GB.
• Editor: quotes last 15 minutes, up to 25 steps per call, with at most 6 paid and 6 destructive steps, 60 editing calls a minute per person, and a default cap of 2,000 credits a day.
• Meta applies its own rate limits to each ad account. When one is hit, the assistant is told the request was rate limited.

Prompts

The server also offers 6 ready-made prompts. Some assistants show them as slash commands. Arguments in bold are required.

Example requests

• Read

  What changed across Meta and Google last week, and which creative is behind it?

  Uses the account, Google Ads and creative tools. Nothing is changed.

• Read

  Tear down the last twenty ads our closest competitor shipped. Which hooks have we never run?

  Uses the competitor tools.

• Read

  Audit the account. Where is budget sitting in ad sets that stopped converting?

  Uses the account audit tools.

• Change

  Pause the three Meta ad sets with the highest cost per result this month.

  Needs Meta ads changes switched on. The assistant shows a draft first and waits for your yes.

• Change

  Draft a Google Search campaign for our summer sale, 1,500 a day, targeting Mumbai.

  Needs Google Ads changes switched on. The campaign is created paused, and only after your yes.

• Credits

  Make three 9:16 images for the hook we just found. Tell me the cost before you spend anything.

  Needs Generation tools switched on. The assistant should quote the cost and wait for your approval.

Data and privacy

• The assistant receives only what the tools it calls return. That content is then handled by the assistant's own provider under that provider's terms.
• Marxx logs each tool call by tool name, without its arguments or results.
• Marxx keeps what the change and creative tools produce so you can use it: drafts and change history, moodboards, boards, generated media and editor projects, all inside the client's workspace.
• Tokens are bound to this server's address. There are no API keys.

Read the privacy policy and the terms for how Marxx handles personal data and the rules of use.

Errors and troubleshooting

Tool errors come back to the assistant as readable messages, which it should relay to you.

Support

Email apurv@marxx.ai with a screenshot of what you see, or book a call. Setup help is in Use Marxx inside Claude, ChatGPT and Cursor.