πŸ€–chiliad
ClaudePricing
Developer docs

MCP server reference

chiliad exposes its script hosting, account assignment, per-account configuration and execution history as a remote Model Context Protocol server. Any MCP client that supports streamable HTTP and OAuth 2.1 can connect. Setting it up in Claude without code? Start with the Claude connector page.

On this page

  • Overview
  • Connect a client
  • Authentication
  • Workspace and access
  • Requests and responses
  • Rate limits and quotas
  • Script code contract
  • Typical workflow
  • Tool reference
    • Session
    • Scripts
    • Accounts and assignments
    • Configuration
    • Google Ads data
    • Marketplace
  • Errors

Overview

Endpointhttps://app.chiliad.io/api/mcp
TransportStreamable HTTP. The legacy HTTP+SSE transport is not offered.
AuthenticationOAuth 2.1 authorization code with PKCE. No API keys.
Capabilities21 tools (12 read-only, 9 write). No resources or prompts.
Request timeout60 seconds per request
Server namechiliad

Use the endpoint exactly as shown. A trailing slash (/api/mcp/) returns a redirect that most MCP clients do not follow.

On initialize the server returns instructions for the model: call get_authoring_guide before writing script code, and relay the loader returned by create_script to the user unchanged. If your client does not pass server instructions to the model, include that guidance in your own system prompt.

Connect a client

Claude apps

In claude.ai or the Claude desktop app, open Settings β†’ Connectors β†’ Add custom connector and paste the endpoint URL. Step-by-step instructions are in How to connect Claude to chiliad.

Claude Code

Terminal
claude mcp add --transport http chiliad https://app.chiliad.io/api/mcp

Then run /mcp inside Claude Code and complete the sign-in in your browser.

Other MCP clients

Clients that read an mcpServers config take a remote HTTP entry. The key names vary slightly between clients; the URL is what matters.

MCP client config
{
  "mcpServers": {
    "chiliad": {
      "type": "http",
      "url": "https://app.chiliad.io/api/mcp"
    }
  }
}

The client must implement the MCP authorization flow described below. Clients that only support static headers or stdio servers cannot connect.

Authentication

The server follows the MCP authorization specification. chiliad is the protected resource, and its authorization server issues the tokens. A compliant client discovers everything from the endpoint URL:

  1. A request without a valid token returns 401 with a pointer to the protected-resource metadata.
  2. https://app.chiliad.io/.well-known/oauth-protected-resource (RFC 9728) names the authorization server.
  3. The authorization server metadata (RFC 8414) lists the authorization, token and registration endpoints. It is also served from https://app.chiliad.io/.well-known/oauth-authorization-server for clients that look it up on the MCP server's origin.
  4. The client registers itself with dynamic client registration (RFC 7591), then runs the authorization code flow with PKCE.
  5. The user signs in to chiliad and approves the client on a consent screen.
  6. The client sends the access token as Authorization: Bearer … on every request.
Unauthenticated response
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://app.chiliad.io/.well-known/oauth-protected-resource"

Access tokens are JWTs that identify one chiliad user and expire. When a request starts returning 401, refresh the token or run the flow again. There are no per-tool scopes: a token can call every tool that the user's role allows. Users revoke access by removing the connector in their client.

Workspace and access

  • One workspace per token. Calls run in the workspace the user joined first. Switching workspaces over MCP is not supported yet; whoami reports the active one and lists the others.
  • The user's role applies. A member restricted to specific Google Ads accounts sees and changes only those accounts, exactly as in the dashboard.
  • Plan limits apply. Script count, loader access, premium marketplace scripts and execution history retention follow the workspace plan.
  • Google Ads is read-only. No tool changes a Google Ads account directly. run_gaql accepts a single SELECT; account changes happen only when a deployed script runs.
  • Changes are audited. Code saved over MCP is recorded in the script's version history, and per-account value changes in its config history.

Billing, team membership and Google login connections are not reachable over MCP. The full list is in What can Claude access through the chiliad connector?

Requests and responses

Requests are JSON-RPC 2.0 messages sent with POST. Send Accept: application/json, text/event-stream; the response may arrive as either.

List tools
curl -X POST https://app.chiliad.io/api/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
Call a tool
curl -X POST https://app.chiliad.io/api/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "run_gaql",
      "arguments": {
        "account": "123-456-7890",
        "query": "SELECT campaign.id, campaign.name FROM campaign WHERE campaign.status = 'ENABLED'",
        "limit": 10
      }
    }
  }'

Every tool returns a single text content block written for a language model to read: a short summary, then lists, code fences or JSON where relevant. There is no structured output schema, so do not parse the text with strict rules; pass it to the model.

Successful result
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "10 row(s) from Acme Store (123-456-7890) in 412ms. ..." }]
  }
}

Scripts and accounts accept flexible identifiers. A script argument takes the script's UUID or its slug. An account argument takes the Google Ads customer ID (with or without dashes) or the account's UUID from list_accounts.

Rate limits and quotas

LimitValue
All tool calls60 per minute, per user
Write tool calls20 per minute, per user (counted within the 60)
Script code size200,000 characters
GAQL rows per query1,000 (default 50)
Execution history look-back90 days, capped by the plan's retention

A rate-limited call is not an HTTP error. It returns a tool result with isError: true and the number of seconds to wait.

Script code contract

chiliad scripts are library-only. You submit the logic; the platform generates a small loader that the user pastes into Google Ads once. The loader fetches the hosted code on every run, handles manager (MCC) accounts, applies per-account configuration and reports each execution.

Minimal valid script
// Label applied to campaigns this script manages
var CAMPAIGN_LABEL = "Managed";
// How many days of data to analyze
var LOOKBACK_DAYS = 30;

function main() {
  var rows = AdsApp.search(
    "SELECT campaign.id, campaign.name, metrics.cost_micros " +
    "FROM campaign WHERE segments.date DURING LAST_30_DAYS"
  );
  while (rows.hasNext()) {
    var row = rows.next();
    Logger.log(row.campaign.name + ": " + row.metrics.costMicros / 1000000);
  }
}

create_script and update_script_code validate the code before saving it.

OutcomeRule
RejectedNo function main() entry point.
RejectedThe code defines chiliadAnalytics(). The loader injects it; calling chiliadAnalytics(message) to report an error is allowed.
RejectedThe code includes a ScriptApp wrapper.
WarningThe code calls chiliadAnalytics('success'). The loader reports success itself, so the run is counted twice.
WarningThe code uses AdsManagerApp. The loader then skips its own manager account handling, so the script must cover both manager and single accounts.
WarningNo top-level UPPER_SNAKE_CASE var config.

Warnings are returned in the tool result and the code is still saved. The complete contract, including GAQL conventions, Preview mode handling and Google service authorization, is the text returned by get_authoring_guide.

Updated code reaches Google Ads on the script's next run. The user re-pastes the loader only when top-level config variables are added or renamed.

Typical workflow

  1. whoami to confirm the workspace and plan.
  2. get_authoring_guide before generating any code.
  3. list_accounts, then run_gaql to read real campaign IDs, budgets and labels.
  4. create_script. Show the returned loader and setup steps to the user as they are.
  5. set_script_variables to declare the values that differ between accounts.
  6. assign_script, then set_account_config for each account's overrides.
  7. After the first run, get_script_executions to check results. Fix failures with update_script_code.

On a manager account the loader runs the script only in assigned accounts. With no assignments it skips the run, so assign accounts before the first execution.

Tool reference

Generated from the server's tool definitions. Descriptions are the text served to the client in tools/list. Tools marked write change workspace data and count toward the write rate limit; the rest carry the MCP readOnlyHint annotation.

Session

Identify the connected user and workspace, and fetch the script authoring contract.

whoami

read-only
Who am I

Shows the connected chiliad account: user email, active workspace, plan, plan limits, and script count. Call this first if unsure which workspace scripts will be created in.

No parameters.

get_authoring_guide

read-only
Get script authoring guide

Returns the chiliad script authoring contract. ALWAYS call this before writing or editing script code: chiliad scripts are library-only (function main() + top-level var config) and the platform injects the loader, MCC dispatch, and analytics reporting.

No parameters.

Scripts

Create, read, update, archive and restore scripts, fetch the loader, and read execution history.

list_scripts

read-only
List scripts

Lists the workspace's Google Ads scripts with status and run stats. Returns names, slugs, statuses, health, and run counts (no code β€” use get_script for code).

ParameterTypeDescription
status
optional
"active" | "inactive" | "paused" | "not_configured" | "draft" | "error"Filter by script status
limit
optional
integer
1–100
β€”
Default: 50
include_archived
optional
booleanInclude archived (deleted) scripts
Default: false

get_script

read-only
Get script

Fetches a script's metadata, run stats, config variables, and code by ID or slug.

ParameterTypeDescription
script
required
stringScript ID or slug
include_code
optional
booleanβ€”
Default: true

create_script

write
Create script

Creates a new Google Ads script in the chiliad workspace and returns the loader + setup steps for deploying it in Google Ads. The code must follow the chiliad library contract β€” call get_authoring_guide first if you haven't.

ParameterTypeDescription
name
required
string
1–120 chars
Human-readable script name
description
optional
string
max 500 chars
One-sentence description of what the script does
code
required
string
1–200,000 chars
The library code (function main() + top-level var config)
type
optional
stringScript type, e.g. "automation" (default), "reporting", "monitoring"
frequency
optional
stringIntended run frequency, e.g. "daily", "hourly", "manual" (default)

update_script_code

write
Update script code

Replaces a script's code (the previous version is kept in version history). The hosted library updates in place β€” Google Ads picks it up on the next run without re-pasting the loader, unless top-level config variables were added or renamed (then fetch get_loader again).

ParameterTypeDescription
script
required
stringScript ID or slug
code
required
string
1–200,000 chars
The full replacement library code

get_loader

read-only
Get loader script

Returns the loader script the user pastes into Google Ads (Tools β†’ Bulk Actions β†’ Scripts) plus setup steps. The loader fetches the hosted library, so it only needs to be pasted once.

ParameterTypeDescription
script
required
stringScript ID or slug

get_script_executions

read-only
Get script executions

Shows a script's recent execution history: success rate, health, and per-run logs including error messages. Use this to check whether a deployed script ran and to debug failures (then fix with update_script_code).

ParameterTypeDescription
script
required
stringScript ID or slug
days
optional
integer
1–90
Look-back window in days (clamped to the plan's analytics retention)
Default: 30
limit
optional
integer
1–100
Max log entries to return
Default: 25

delete_script

write
Delete (archive) a script

Archives a script β€” it's hidden from list_scripts and the dashboard but recoverable with restore_script, and its version history and analytics are kept. NOTE: this does NOT stop it in Google Ads β€” if the loader is already installed in an account it keeps running the hosted code, so remove it there too if you want it to stop. Use include_archived on list_scripts to find archived scripts.

ParameterTypeDescription
script
required
stringScript ID or slug

restore_script

write
Restore an archived script

Restores a previously archived (deleted) script back into the workspace listings. Find archived scripts with list_scripts include_archived=true.

ParameterTypeDescription
script
required
stringScript ID or slug

Accounts and assignments

List connected Google Ads accounts and control which accounts a script runs in.

list_accounts

read-only
List Google Ads accounts

Lists the Google Ads accounts connected to this workspace (only those the signed-in member can access), with customer ID, manager flag, currency, timezone, and how many scripts are assigned to each. Use the returned customer ID or UUID to assign scripts and set per-account config.

ParameterTypeDescription
query
optional
stringFilter by account name or customer ID
limit
optional
integer
1–100
β€”
Default: 50

list_account_scripts

read-only
List script assignments

Shows which scripts are assigned to which accounts, with each assignment's status and the config keys that are overridden per account. Pass an account (customer ID or UUID) to scope to one account, or omit it for the whole workspace.

ParameterTypeDescription
account
optional
stringAccount customer ID or UUID; omit for all accounts

assign_script

write
Assign script to accounts

Assigns a script to one or more Google Ads accounts so it runs there. Accepts a script ID/slug and a list of account customer IDs or UUIDs. Already-assigned accounts are skipped. After assigning, set per-account config with set_account_config.

ParameterTypeDescription
script
required
stringScript ID or slug
accounts
required
string[]
1–200 items
Account customer IDs or UUIDs to assign the script to

unassign_script

write
Unassign script from account

Removes a script from a single Google Ads account (the script and its code are untouched β€” only the assignment and that account's per-account config are removed).

ParameterTypeDescription
script
required
stringScript ID or slug
account
required
stringAccount customer ID or UUID

Configuration

Declare a script's config variables and override their values per account.

set_script_variables

write
Declare script config variables

Declares the user-editable config variables for a script (key, label, type, default). These become the loader's Configuration section AND the set of keys a per-account config may override. Replaces the full variable set β€” call get_script first to see current variables if amending. Keys must be valid identifiers (they become `var KEY = ...` in the script).

ParameterTypeDescription
script
required
stringScript ID or slug
variables
required
object[]
1–50 items
β€”
variables[].key
required
string
min 1 chars
Identifier, e.g. LOOKBACK_DAYS (letters/digits/_/$, not starting with a digit)
variables[].label
optional
stringHuman-readable label; defaults to the key
variables[].type
optional
"text" | "url" | "number" | "boolean" | "json"Value type; defaults to text
variables[].defaultValue
optional
stringDefault value as a string (numbers/booleans are coerced by type)

get_account_config

read-only
Get per-account config

Returns a script's effective config for one account: the declared variable defaults merged with that account's overrides, and which keys are overridden.

ParameterTypeDescription
script
required
stringScript ID or slug
account
required
stringAccount customer ID or UUID

set_account_config

write
Set per-account config

Sets or clears per-account overrides for a script's config variables (a partial map of variable key β†’ value; unspecified keys keep their existing value or default). Pass null as a value to clear that override so the account falls back to the script default. The script must be assigned to the account first (assign_script) and the keys must be declared (set_script_variables). Values are stored as strings.

ParameterTypeDescription
script
required
stringScript ID or slug
account
required
stringAccount customer ID or UUID
config
required
map of string β†’ string | nullPartial map of declared variable key β†’ override value, or null to clear the override (back to the default)

Google Ads data

Query one connected account with read-only GAQL.

run_gaql

read-only
Run a GAQL query

Runs a single read-only GAQL (Google Ads Query Language) SELECT against one connected account and returns the rows as JSON. Use it to inspect real account data β€” campaigns, budgets, labels, conversion actions, metrics β€” so you can configure scripts with actual IDs and sensible thresholds instead of guessing. Read-only: only SELECT is allowed. A LIMIT is appended automatically if you omit one. Example: SELECT campaign.id, campaign.name, campaign_budget.amount_micros FROM campaign WHERE campaign.status = 'ENABLED'.

ParameterTypeDescription
account
required
stringAccount customer ID or UUID to query (from list_accounts)
query
required
string
1–5,000 chars
A single read-only GAQL SELECT statement
limit
optional
integer
1–1,000
Max rows to return; a LIMIT is appended if your query omits one
Default: 50

Marketplace

Search the catalog of ready-made scripts and install one into the workspace.

search_marketplace

read-only
Search marketplace

Searches the chiliad marketplace of ready-made Google Ads scripts by keyword, category, or access tier.

ParameterTypeDescription
query
optional
stringKeyword matched against name, description, and tags
category
optional
stringβ€”
tier
optional
"free" | "premium" | "paid"β€”
limit
optional
integer
1–50
β€”
Default: 20

get_marketplace_script

read-only
Get marketplace script

Fetches a marketplace script's details: overview, setup steps, config variables, and expected output.

ParameterTypeDescription
id
required
stringMarketplace script ID (from search_marketplace)
include_code
optional
booleanβ€”
Default: false

install_marketplace_script

write
Install marketplace script

Installs a marketplace script into the workspace as the user's own editable copy, and returns the loader + setup steps for deploying it in Google Ads.

ParameterTypeDescription
id
required
stringMarketplace script ID (from search_marketplace)

Errors

Authentication failures are HTTP 401 responses. Everything else is reported inside a normal JSON-RPC result with isError: true and a message that says what to do next.

Tool error
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "Script not found in this workspace. Use list_scripts to see available scripts." }],
    "isError": true
  }
}
MessageCause
HTTP 401 with a WWW-Authenticate headerThe bearer token is missing, expired, malformed, or was issued by a different authorization server. Refresh the token or run the OAuth flow again.
Not authenticated β€” reconnect the chiliad connector and try again.The token verified but carries no user. Re-authorize.
Rate limit reached β€” try again in Ns.More than 60 tool calls in a minute for this user.
Too many changes in a short time β€” try again in Ns.More than 20 mutating tool calls in a minute for this user.
No workspace found for this account.The user completed OAuth but has never set up a workspace. They need to sign in to the dashboard once.
Script not found in this workspace.The ID or slug does not match a script in the active workspace.
The script code doesn't match the chiliad library contract: …create_script or update_script_code rejected the code. The message lists each violation; nothing was saved.
Loader scripts are available on paid plans.The workspace is on the free plan. The script is saved, but get_loader is gated.
Something went wrong on chiliad's side β€” please try again.An unexpected server error. Safe to retry read-only tools; check state before retrying a mutating one.

Google Ads query errors from run_gaql include Google's error code and the offending field. Questions or something missing? Write to hello@chiliad.io.

πŸ€–chiliad

The platform for managing and automating Google Ads scripts at scale. Built for PPC agencies and freelancers.

chiliad β€” Google Ads Script Management - Monitor and manage Google Ads scripts across every account | Product Hunt

Product

  • Use Cases
  • Features
  • Claude connector
  • Pricing
  • Marketplace
  • Blog
  • About
  • Roadmap
  • Changelog

Support

  • Contact Us
  • Help Center
  • Developer docs
  • Terms of Service
  • Privacy Policy

Β© 2026 chiliad. All rights reserved.