Overview
| Endpoint | https://app.chiliad.io/api/mcp |
| Transport | Streamable HTTP. The legacy HTTP+SSE transport is not offered. |
| Authentication | OAuth 2.1 authorization code with PKCE. No API keys. |
| Capabilities | 21 tools (12 read-only, 9 write). No resources or prompts. |
| Request timeout | 60 seconds per request |
| Server name | chiliad |
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
claude mcp add --transport http chiliad https://app.chiliad.io/api/mcpThen 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.
{
"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:
- A request without a valid token returns
401with a pointer to the protected-resource metadata. https://app.chiliad.io/.well-known/oauth-protected-resource(RFC 9728) names the authorization server.- 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-serverfor clients that look it up on the MCP server's origin. - The client registers itself with dynamic client registration (RFC 7591), then runs the authorization code flow with PKCE.
- The user signs in to chiliad and approves the client on a consent screen.
- The client sends the access token as
Authorization: Bearer …on every request.
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.
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"}'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.
{
"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
| Limit | Value |
|---|---|
| All tool calls | 60 per minute, per user |
| Write tool calls | 20 per minute, per user (counted within the 60) |
| Script code size | 200,000 characters |
| GAQL rows per query | 1,000 (default 50) |
| Execution history look-back | 90 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.
// 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.
| Outcome | Rule |
|---|---|
| Rejected | No function main() entry point. |
| Rejected | The code defines chiliadAnalytics(). The loader injects it; calling chiliadAnalytics(message) to report an error is allowed. |
| Rejected | The code includes a ScriptApp wrapper. |
| Warning | The code calls chiliadAnalytics('success'). The loader reports success itself, so the run is counted twice. |
| Warning | The code uses AdsManagerApp. The loader then skips its own manager account handling, so the script must cover both manager and single accounts. |
| Warning | No 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
whoamito confirm the workspace and plan.get_authoring_guidebefore generating any code.list_accounts, thenrun_gaqlto read real campaign IDs, budgets and labels.create_script. Show the returned loader and setup steps to the user as they are.set_script_variablesto declare the values that differ between accounts.assign_script, thenset_account_configfor each account's overrides.- After the first run,
get_script_executionsto check results. Fix failures withupdate_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.
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.
Scripts
Create, read, update, archive and restore scripts, fetch the loader, and read execution history.
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).
| Parameter | Type | Description |
|---|---|---|
statusoptional | "active" | "inactive" | "paused" | "not_configured" | "draft" | "error" | Filter by script status |
limitoptional | integer1–100 | — Default: 50 |
include_archivedoptional | boolean | Include archived (deleted) scripts Default: false |
Fetches a script's metadata, run stats, config variables, and code by ID or slug.
| Parameter | Type | Description |
|---|---|---|
scriptrequired | string | Script ID or slug |
include_codeoptional | boolean | — Default: true |
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.
| Parameter | Type | Description |
|---|---|---|
namerequired | string1–120 chars | Human-readable script name |
descriptionoptional | stringmax 500 chars | One-sentence description of what the script does |
coderequired | string1–200,000 chars | The library code (function main() + top-level var config) |
typeoptional | string | Script type, e.g. "automation" (default), "reporting", "monitoring" |
frequencyoptional | string | Intended run frequency, e.g. "daily", "hourly", "manual" (default) |
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).
| Parameter | Type | Description |
|---|---|---|
scriptrequired | string | Script ID or slug |
coderequired | string1–200,000 chars | The full replacement library code |
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.
| Parameter | Type | Description |
|---|---|---|
scriptrequired | string | Script ID or slug |
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).
| Parameter | Type | Description |
|---|---|---|
scriptrequired | string | Script ID or slug |
daysoptional | integer1–90 | Look-back window in days (clamped to the plan's analytics retention) Default: 30 |
limitoptional | integer1–100 | Max log entries to return Default: 25 |
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.
| Parameter | Type | Description |
|---|---|---|
scriptrequired | string | Script ID or slug |
Restores a previously archived (deleted) script back into the workspace listings. Find archived scripts with list_scripts include_archived=true.
| Parameter | Type | Description |
|---|---|---|
scriptrequired | string | Script ID or slug |
Accounts and assignments
List connected Google Ads accounts and control which accounts a script runs in.
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.
| Parameter | Type | Description |
|---|---|---|
queryoptional | string | Filter by account name or customer ID |
limitoptional | integer1–100 | — Default: 50 |
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.
| Parameter | Type | Description |
|---|---|---|
accountoptional | string | Account customer ID or UUID; omit for all 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.
| Parameter | Type | Description |
|---|---|---|
scriptrequired | string | Script ID or slug |
accountsrequired | string[]1–200 items | Account customer IDs or UUIDs to assign the script to |
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).
| Parameter | Type | Description |
|---|---|---|
scriptrequired | string | Script ID or slug |
accountrequired | string | Account customer ID or UUID |
Configuration
Declare a script's config variables and override their values per account.
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).
| Parameter | Type | Description |
|---|---|---|
scriptrequired | string | Script ID or slug |
variablesrequired | object[]1–50 items | — |
variables[].keyrequired | stringmin 1 chars | Identifier, e.g. LOOKBACK_DAYS (letters/digits/_/$, not starting with a digit) |
variables[].labeloptional | string | Human-readable label; defaults to the key |
variables[].typeoptional | "text" | "url" | "number" | "boolean" | "json" | Value type; defaults to text |
variables[].defaultValueoptional | string | Default value as a string (numbers/booleans are coerced by type) |
Returns a script's effective config for one account: the declared variable defaults merged with that account's overrides, and which keys are overridden.
| Parameter | Type | Description |
|---|---|---|
scriptrequired | string | Script ID or slug |
accountrequired | string | Account customer ID or UUID |
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.
| Parameter | Type | Description |
|---|---|---|
scriptrequired | string | Script ID or slug |
accountrequired | string | Account customer ID or UUID |
configrequired | map of string → string | null | Partial 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.
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'.
| Parameter | Type | Description |
|---|---|---|
accountrequired | string | Account customer ID or UUID to query (from list_accounts) |
queryrequired | string1–5,000 chars | A single read-only GAQL SELECT statement |
limitoptional | integer1–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.
Searches the chiliad marketplace of ready-made Google Ads scripts by keyword, category, or access tier.
| Parameter | Type | Description |
|---|---|---|
queryoptional | string | Keyword matched against name, description, and tags |
categoryoptional | string | — |
tieroptional | "free" | "premium" | "paid" | — |
limitoptional | integer1–50 | — Default: 20 |
Fetches a marketplace script's details: overview, setup steps, config variables, and expected output.
| Parameter | Type | Description |
|---|---|---|
idrequired | string | Marketplace script ID (from search_marketplace) |
include_codeoptional | boolean | — Default: false |
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.
| Parameter | Type | Description |
|---|---|---|
idrequired | string | Marketplace 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.
{
"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
}
}| Message | Cause |
|---|---|
| HTTP 401 with a WWW-Authenticate header | The 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.