Documentation

Connect a headless agent (Hermes, n8n, cron, scripts)

The OAuth 2.1 flow (used by Claude.ai) needs an interactive browser for consent — which a headless agent doesn't have. For those clients, gadspilot supports a Personal Access Token (PAT): a long-lived token you pass as an Authorization: Bearer header. OAuth stays available and unchanged — the PAT is an additional, optional method.

1. Generate a token

Open your Google Ads dashboard → “Connect an agent or script (headless)” block → name it (e.g. “Hermes VPS”) → Generate token. The token is shown once — copy it immediately. It carries access to all your Google Ads resources and never expires until you revoke it.

2. Test the connection (curl)

Confirm the token works by listing the available tools:

curl -sS https://gadspilot.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A JSON response listing tools means you're connected. A 401 invalid_token means the token is wrong, revoked, or missing the Bearer prefix.

3. Wire it into your agent

Claude Code (CLI), no browser:

claude mcp add --transport http gadspilot-ads https://gadspilot.com/mcp --header "Authorization: Bearer YOUR_TOKEN"

Any MCP client (JSON config):

{
  "mcpServers": {
    "gadspilot-ads": {
      "type": "http",
      "url": "https://gadspilot.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Raw JSON-RPC (custom script / Hermes): POST to https://gadspilot.com/mcp with the Authorization: Bearer header. Each call is a standard MCP JSON-RPC 2.0 message (tools/list, then tools/call).