The Cogny CLI: Your Marketing MCP, Scriptable From the Command Line

Most of the writing about MCP — ours included — assumes a chat window. You add a connector, the tools show up in your AI client's tool catalog, you ask a question, the model picks a tool. That's the happy path, and when it works it's great.

But "when it works" is doing a lot of lifting.

If you've ever tried to wire a native MCP server into an agent on a fresh machine, you know the failure modes. The OAuth flow opens a browser the agent can't see. The static API key gets ignored because the client prefers OAuth and the server sits there saying "needs authentication." You add the server, but the tools don't appear until you restart the whole process — and the agent you're talking to is the process. For a human clicking through a UI, these are speed bumps. For an autonomous agent in a sandbox with no browser, they're walls.

The Cogny CLI is how we got around all of it.

It exposes every Cogny MCP tool as an ordinary command-line subcommand. The same Google Ads, GA4, Search Console, BigQuery, Meta, TikTok, X, LinkedIn, Mailchimp and Discord tools you'd get over MCP — except you call them from Bash:

cogny tools call execute_bigquery_sql --input '{"query":"select 1"}'

No MCP server to configure. No OAuth browser dance. No restart. It works on day one, in any environment that has a shell — which, crucially, includes every coding agent on the planet.

TL;DR

The Cogny CLI wraps the Cogny MCP endpoint, exposing every tool as a cogny tools call <name> subcommand you can run from Bash.
It sidesteps the three things that break native MCP for agents: OAuth browser flows, ignored API keys, and the restart-to-discover-tools requirement.
Onboarding is fully agentic. npx @cogny/cli init signs the user up using their git config user.email, grants 15 free credits, and writes an API key — no human, no card, no browser.
Because tools are just commands, they're scriptable: pipe JSON in, parse JSON out, drop calls into cron, build runbooks for standard operations like weekly ad audits.
It's the install surface behind cogny.com/SKILL.md — paste that URL into your coding agent and it bootstraps itself.
Native MCP is still there if you want it (cogny mcp-config --write). The CLI is the path that works everywhere, immediately.

What it actually is

Cogny is a managed MCP endpoint over your marketing data — connect Google Ads, GA4, Search Console, BigQuery and the rest, and an AI client can query them through one protocol. We've written about why that matters for marketers who are tired of exporting CSVs into chat windows.

The CLI is the same endpoint, addressed differently. Every tool the MCP server exposes becomes a subcommand. So instead of registering a server and hoping the tool shows up in your catalog, you run:

cogny tools list                 # discover every available tool
cogny tools call list_integrations   # which channels are connected
cogny status                     # subscription, channels, credits

And to call a tool with arguments, you pass JSON — either inline or piped from stdin:

# inline
cogny tools call execute_bigquery_sql --input '{"query":"select 1"}'

# or pipe a payload
cat payload.json | cogny tools call execute_bigquery_sql --stdin

The input schema for every tool is right there in cogny tools list --json, under each tool's inputSchema. An agent reads the schema, constructs the JSON, runs the command, parses the result. No guessing.

To make that concrete — and so an agent reading this page can bootstrap without a live cogny tools list --json call — here's the actual inputSchema for execute_bigquery_sql:

{
  "name": "execute_bigquery_sql",
  "description": "Run a read-only SQL query against the connected BigQuery warehouse. Metered against the workspace credit balance — prefer LIMIT and date filters.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "A standard BigQuery SQL query. Use fully-qualified `dataset.table` names from inspect_schema; avoid SELECT * on raw event tables."
      },
      "dry_run": {
        "type": "boolean",
        "description": "If true, validate the query and return the estimated bytes scanned without executing or spending credits.",
        "default": false
      }
    },
    "required": ["query"]
  }
}

So the call is just that schema, filled in:

cogny tools call execute_bigquery_sql --input '{"query":"select 1","dry_run":true}'

That's the whole model. It's deliberately boring, because boring is what survives contact with a thousand different agent environments.

Why a CLI beats a native MCP connector (for agents)

Native MCP is a beautiful abstraction for a human in a polished client. For an agent — especially one running headless, in a container, in a CI job, or inside another tool's sandbox — the CLI wins on three specific points.

1. No OAuth browser dance

Native MCP connectors authenticate with OAuth. OAuth assumes a browser and a human to click "Authorize." An autonomous agent in a sandbox has neither. The Cogny CLI authenticates with an API key it writes to ~/.cogny/config.json during signup — no browser, no interactive step. The agent never has to hand control back to a human just to get connected.

2. No "needs authentication" dead-end

Some clients — Claude Code among them, as of this writing — prefer OAuth over static Authorization headers and will quietly ignore a configured API key, leaving a native MCP server stuck on "needs authentication" forever. We've watched agents loop on this. The CLI path doesn't touch that code at all: it carries the key itself and calls the API directly. Same tools, no auth limbo.

3. No restart to discover tools

When you add a native MCP server, the agent has to restart to discover the new tools. But the agent you're working with is the running process — you can't restart it mid-conversation without losing the thread. With the CLI, cogny tools call ... works the instant cogny init finishes, in the same session. The agent signs the user up and runs the first audit without ever dropping the conversation.

None of this means native MCP is bad. If your client surfaces MCP tools natively and you want them in the catalog, run cogny mcp-config --agent claude-code --write and restart. The CLI is simply the path that has zero preconditions — which is exactly what you want when an agent is driving.

Agentic onboarding: no human in the loop

This is the part we're proudest of.

A user pastes a single URL into their coding agent — Claude Code, Codex, Cursor, Gemini CLI, whatever — and says "read https://cogny.com/SKILL.md and follow the setup." The agent fetches the manifest and runs three commands:

# 1. Make the CLI available (npx needs no PATH setup)
alias cogny="npx @cogny/cli"

# 2. Sign the user up with their git email — no card, 15 free credits
cogny init --agent claude-code

# 3. Start working
cogny tools call list_integrations

There's no signup form. No email verification click. No "check your inbox." cogny init reads the user's git config user.email, creates (or recovers) a Cogny Solo workspace tied to that address, grants 15 free MCP calls for the month, and persists an API key locally. The agent confirms what landed — "Workspace ready for you@example.com — 23 tools, 0 channels connected, 15 free credits" — and immediately moves on to doing actual work.

The user went from "never heard of Cogny" to "Claude is auditing my Google Ads account" without filling in a single field or leaving the chat. That's the bar we set for agent-native onboarding, and the CLI is what clears it. (No shell? The same manifest hands off gracefully to a manual MCP-connector setup for web clients like Claude.ai and ChatGPT — but anywhere there's a Bash tool, it's fully automatic.)

Scripting and runbooks: the real unlock

Once your marketing tools are commands, everything you already know about composing commands applies. This is where the CLI stops being a convenience and starts being a different category of thing.

Pipe data between tools. The output is JSON. Pipe it into jq, into a file, into the next call, into another program. Standard Unix plumbing, now wired to your ad accounts.

Drop calls into cron. A native MCP connector needs a live agent session to fire. A CLI command needs nothing but a scheduler. Want a Google Ads anomaly check every morning at 7am? That's a crontab line:

# 7am daily: pull yesterday's Google Ads spend & conversions
0 7 * * * cogny tools call tool_execute_gaql \
  --input '{"query":"SELECT campaign.name, metrics.cost_micros, metrics.conversions FROM campaign WHERE segments.date DURING YESTERDAY"}' \
  >> ~/reports/gads-$(date +\%F).json

Build runbooks for standard operations. This is the big one. Most marketing ops are the same handful of checks run on a cadence — pacing against budget, search-term mining, CPA/ROAS watchdog, impression-share erosion. With the CLI you write each as a small, reviewable script: a sequence of cogny tools call invocations an agent (or a human) executes, with the JSON results feeding the next step. The runbook becomes a versioned artifact in your repo, not tribal knowledge in someone's head. The agent runs the runbook; you read the output.

A weekly Google Ads health check, for instance, is just: list_integrations to confirm the account is live → inspect_schema so you query the right tables → a GAQL pull for the last 7 days → a second pull for the prior 7 → diff and flag. Five calls, one script, runnable by a human or an agent, every Monday, forever.

Compose with the agent's own reasoning. Because the agent runs these from Bash, it interleaves them with everything else it does — reading your repo, writing the analysis, opening a PR. The marketing data lives in the same loop as the code. That's the harness idea, reduced to its smallest useful unit: a command.

A worked example

Say an agent has just onboarded a user with a Google Ads account and wants to surface the obvious wins. The whole flow is shell commands:

# What's connected?
cogny tools call list_integrations

# Last 30 days by campaign, sorted by spend
cogny tools call tool_execute_gaql --input '{
  "query": "SELECT campaign.name, metrics.cost_micros, metrics.conversions, metrics.ctr FROM campaign WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.cost_micros DESC"
}'

# Persist the finding so the next session does not redo this work
cogny tools call write_context_node --input '{
  "title": "Q2 Google Ads spend concentration",
  "body": "Top campaign = 58% of spend, CTR 0.9% vs account avg 2.1%."
}'

Two reads and a write. The agent now knows where the money goes, where the underperformance is, and — because it wrote the finding to Cogny's context tree — next week's run starts from that conclusion instead of rediscovering it. The credit meter ticks down by a few calls, not a few dozen, because the schema-aware tooling means no flailing exploratory queries.

Where it fits

The CLI isn't a replacement for the chat experience — it's the substrate underneath it. If you're a marketer who wants to ask questions in plain language, the managed MCP endpoint and a chat client is still the front door. If you're an agent, or a developer building automation, or anyone who wants marketing operations to live in scripts and runbooks instead of dashboards, the CLI is the door that was actually built for you.

It's the same data, the same tools, the same 1.2×-margin credit metering. The difference is that it's cogny tools call away from anything that has a shell — which, increasingly, is everything.

Paste cogny.com/SKILL.md into your coding agent and let it set itself up. Fifteen free calls, no card, about thirty seconds. The first audit runs in the same session.

Our commitment to agent-friendliness

The CLI isn't a one-off. It's an expression of how we think about building Cogny: every capability should be reachable by an autonomous agent, not just a human clicking through a UI.

Concretely, that means we hold ourselves to a few rules:

No human-only gates on paths agents need. Onboarding runs from a single command — no forms, no captcha, no email-verification click, no mandatory browser OAuth. Where a human flow exists, a programmatic one exists beside it (API keys via cogny init or the auth.md handshake, not OAuth-only).
Machine-readable surfaces are first-class. A public SKILL.md manifest, an llms.txt, .well-known discovery for auth, server-rendered public pages, JSON-LD structured data (including the HowTo block on this very post), and tool inputSchemas an agent can read before it calls. If an agent has to scrape rendered prose to figure out how to use us, we consider that a bug.
Errors that name the cause and the next step, so an agent can self-correct instead of stalling.
We measure it. Every pull request to Cogny is now scored 1–10 on how well it "sells to agents" — does it widen the agent path or fence it off? This post, and the surfaces above, are us holding ourselves to that bar in public.

The protocol gave AI a way to read your marketing data. The CLI gave your agents a way to script it. The commitment is that it stays that way.