Quick triage checklist

Before digging deeper, confirm the following.

• Are you part of an approved alpha advertiser account?
• Are you querying only accounts and entities you already have permission to access?
• Are you asking for a read-only workflow that is actually in scope for the alpha?
• Are you using a supported MCP surface for your cohort?

Common errors

Fallback: manual config

If you can't use a custom connector / OAuth, or you'd rather manage the connection in a config file, connect by editing claude_desktop_config.json directly with your API key.

The key is stored in a plain-text file, so treat the file as a secret.

Step 0 — Install Node.js (one time)

This path needs Node.js, which provides the npx command used by the config below to connect Claude Desktop to the server with your API key.

Check whether you already have it — open a terminal (macOS: Terminal app; Windows: PowerShell) and run both:

node --version
npx --version

If node shows v20.18.1 or newer (e.g. v20.x, v22.x, or v24.x) and npx also prints a version, you're set — skip to Configure Claude Desktop below. If node is older than v20.18.1 (including any v18/v19), or either command says "command not found" / "not recognized", install/upgrade it — the helper this path runs needs at least Node 20.18.1 and will fail to start on older versions:

• macOS / Windows (recommended for non-developers) — open the download page: nodejs.org/en/download. It auto-detects your OS and offers the LTS release (currently v24.x — the stable, recommended line; if you see an LTS / Current toggle, leave it on LTS, not v26 "Current"). Download the graphical installer it presents:

  • macOS: a .pkg file → double-click it, click Continue → Install, and enter your Mac login password when prompted.
  • Windows: an .msi file → double-click it and click Next through the wizard, keeping every default (in particular leave "Add to PATH" checked).

  The installer includes both node and npx — there's nothing else to pick or configure.

• macOS, if you already use Homebrew — instead of the installer you can run brew install node in the terminal.

After installing, fully close and reopen your terminal (and quit Claude Desktop if it was open) so the freshly installed node/npx are found on your PATH. Then confirm both respond:

node --version    # e.g. v24.16.0
npx --version     # e.g. 11.3.0

If node --version works but npx --version says "not found", reinstall Node.js with the official installer above (most installers include npx, but a partial install sometimes omits it).

That's all you need from the terminal — Claude Desktop handles the rest using the config below. The first launch may take a few seconds the first time npx runs.

Configure Claude Desktop

1. Open your claude_desktop_config.json. In Claude Desktop, go to Settings → Developer → Edit Config — this opens (and, if needed, creates) the file in your default editor.

   If that menu isn't available, open the file directly from disk:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the moloco-ads server. If the file is empty or brand new, paste the whole block below as its entire contents. If it already has content, add the moloco-ads entry inside the mcpServers object — and if there's no mcpServers key yet, add the whole "mcpServers": { … } object alongside whatever is already there (remember the comma between top-level keys):

   JSON

   {
     "mcpServers": {
       "moloco-ads": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote",
           "https://mcp.moloco.cloud/mcp",
           "--header",
           "Authorization:${MOLOCO_AUTH}"
         ],
         "env": {
           "MOLOCO_AUTH": "Bearer <YOUR_CLOUD_API_KEY>"
         }
       }
     }
   }

   Replace <YOUR_CLOUD_API_KEY> with your key (keep the Bearer prefix) and leave everything else exactly as shown.

   Not sure how to merge this into a config that already has content? Copy your current claude_desktop_config.json and the block above into a Claude chat and ask it to combine them. Important: keep <YOUR_CLOUD_API_KEY> as the placeholder and fill in your real key only afterward, so you never share it. If your existing config already holds other secrets (API keys, tokens, passwords for other servers), redact those too before pasting — replace them with placeholders and restore them after.

3. Fully quit Claude Desktop (⌘Q / right-click the tray icon → Quit — closing the window isn't enough) and reopen it. The config is read only at launch.

4. Open a new chat and ask: "What tools do you have in Moloco Ads MCP?"

To rotate the key, edit MOLOCO_AUTH and restart Desktop. If you can use OAuth (see Claude Desktop in Getting started), prefer it — you won't store a key on your machine at all.

401 — "the api key is expired" or "invalid"

A 401 from a tool call means one of:

1. Expired or revoked key. Cloud API keys have a TTL set at issue time. If it's past the expiration date, or the workplace owner revoked it, you'll see 401 on every call. Re-issue in the Moloco Ads Portal under Settings → API Keys and update your client config (see Getting started for the per-client steps).
2. Wrong header form. The bearer header is Authorization: Bearer <key> — note the space and the Bearer prefix. Manual configs and Claude Code commands need it explicit.

After fixing the key, fully quit and reopen the client. Config and headers are read once at launch.

Rate limits

The MCP forwards your calls to Cloud API and inherits its per-ad-account rate limits — default 300 requests / 5 minutes, with stricter caps on a few analytics and reporting endpoints. Background: developer.moloco.cloud/docs/rate-limits.

When the limit is hit, the tool returns a message like "Cloud API rate limit reached — try again after a short pause" and Claude is told not to retry automatically. Wait for the reset window (≤ 5 minutes for most caps); shrink your question's scope if you keep hitting it.

The MCP and the Cloud Portal share the same per-account quota — if you've been heavily clicking around in the portal, the MCP's first calls may already see a depleted budget.

Tool not found / tool list seems short

The tool surface expands across releases. Ask Claude "What Moloco tools do you have?" to see the live list — if something documented isn't there yet, it hasn't shipped to mcp.moloco.cloud.

Still stuck?

Contact [email protected] for more questions.

Capture the relevant log lines and reach out to your Moloco representative.

• Claude Desktop log: ~/Library/Logs/Claude/main.log (macOS) or %APPDATA%\Claude\logs\main.log (Windows).
• Claude Code log: claude mcp get moloco-ads shows connection state; full logs are under ~/.claude/logs/.

Redact your API key before sharing.