Cogny MCP Server
Connect Claude to your marketing data. Query BigQuery, browse reports, manage growth tickets, and build organizational context — all through natural conversation.
What is the Cogny MCP Server?
Cogny's MCP (Model Context Protocol) server lets you connect Claude directly to your marketing data stack. Once connected, Claude can query your BigQuery warehouse, read Cogny's AI-generated reports, manage growth tickets, and access your organizational context — all through natural conversation.
Server URL: https://app.cogny.com/mcp
Protocol: JSON-RPC 2.0 over HTTPS (MCP spec 2024-11-05)
Authentication: OAuth 2.1 (authorization code flow with PKCE) — no API key needed; your MCP client handles the sign-in, and you pick which warehouse to authorize.
Tip: You can also use a warehouse-scoped URL of the form
https://app.cogny.com/mcp/w/<your-warehouse-id>to skip the warehouse picker. Copy the exact URL for your workspace from Settings → MCP inside the app. Both the generic and scoped URLs work everywhere.
Quick Setup
In Claude.ai / Claude Cowork
- Go to Settings → Connectors → Add custom connector
- Enter the name cogny and paste the server URL:
https://app.cogny.com/mcp - Click Add — Claude will prompt you to log in
- In the popup, select your warehouse and click Authorize
- Start chatting — Claude now has access to your marketing data
In ChatGPT
- Go to Settings → Apps → Advanced settings and enable Developer mode
- Click Create app, enter the name Cogny, and paste the server URL:
https://app.cogny.com/mcp - Set Authentication to OAuth, check the risk acknowledgment, and click Create
- In the popup, select your warehouse and click Authorize
- To use it: click + in the chat box → More → Cogny
ChatGPT may prompt you to authorize twice on first use — this is normal.
In Claude Code (CLI)
The fastest route is to let the agent install Cogny itself: paste Read https://cogny.com/SKILL.md and follow the setup instructions. See Install Cogny in Your AI Agent for what that does. To add the MCP server by hand instead:
Run this in your project directory — Claude Code handles the OAuth login automatically:
claude mcp add --transport http cogny https://app.cogny.com/mcp
Or, if you already have a Cogny API token, skip OAuth with a bearer header:
claude mcp add --transport http cogny https://app.cogny.com/mcp --header "Authorization: Bearer YOUR_TOKEN"
In Codex CLI
Run this in your project directory — Codex detects OAuth and opens the authorization flow automatically:
codex mcp add cogny --url https://app.cogny.com/mcp
If the server is already added and you need to authenticate again, run codex mcp login cogny.
Via the API (Anthropic MCP Client)
Use the Anthropic API with the mcp-client-2025-04-04 beta header to connect programmatically against https://app.cogny.com/mcp. See Anthropic's MCP documentation for details.
Available Tools
All tools include MCP safety annotations (readOnlyHint, destructiveHint, etc.) so Claude understands which tools are safe to call without confirmation.
BigQuery Analytics
Query your connected data warehouse directly.
| Tool | Description | Safety |
|---|---|---|
list_datasets | List all BigQuery datasets in your warehouse | Read-only |
list_tables | List tables in a dataset (auto-groups GA4 sharded tables) | Read-only |
inspect_schema | Get column definitions and CREATE TABLE statement | Read-only |
execute_bigquery_sql | Run read-only SQL queries (SELECT/WITH only, 500 row limit) | Read-only |
Example prompt: "What are my top 10 landing pages by conversion rate this month?"
Reports & Visualizations
Access Cogny's AI-generated marketing reports and render interactive charts.
| Tool | Description | Safety |
|---|---|---|
list_reports | List recent reports (SEO, Google Ads, CRO, etc.) | Read-only |
get_report | Get full report content with all sections | Read-only |
get_report_section | Get a section's SQL and chart config | Read-only |
show_report_section | Render an interactive chart visualization | Read-only |
show_metrics | Display configured core KPI metrics with trends | Read-only |
show_budget | Show ad spend vs. monthly budget targets | Read-only |
Example prompt: "Show me this week's SEO performance report"
Growth Tickets
Manage the actionable opportunities Cogny identifies from your data.
| Tool | Description | Safety |
|---|---|---|
list_tickets | List tickets with status/type filtering | Read-only |
get_ticket | Get ticket details, body, and execution history | Read-only |
get_comments | Get the ticket thread — agent notes and human replies, newest first | Read-only |
get_ticket_source_context | Get the report/analysis that created a ticket | Read-only |
get_winner_status | Long-term impact history of a winner ticket (trend, cumulative USD impact, check schedule) | Read-only |
create_ticket | Create a new growth ticket | Write |
update_ticket_status | Move ticket through workflow (new > assigned > doing > analysis) | Write |
add_comment | Add a comment to a ticket | Write |
add_ticket_feedback | Tell Cogny a ticket is useful, already done, wrong, duplicate, or out of scope — feeds the ticket generator; optionally rejects it | Write |
assign_ticket | Assign or unassign a ticket | Write |
link_pr_to_ticket | Link a GitHub PR for auto-status updates | Write |
Example prompt: "What are my open growth tickets? Assign the top-priority one to me."
Leaving feedback on a ticket
add_ticket_feedback records what an agent thinks of a ticket. Cogny reads it
back when generating the next batch, so a ticket marked already_done or
incorrect_data stops recurring. Always explain the verdict — the reasoning is
what future generation learns from.
| Verdict | Means |
|---|---|
useful | Worth doing as written |
already_done | The work described is already in place |
not_actionable | Too vague or underspecified to act on |
incorrect_data | The numbers or the premise are wrong |
duplicate | Already covered by another ticket |
out_of_scope | Not something this workspace does |
Feedback is appended, never overwritten, so earlier entries and human rejection
reasons survive. A negative verdict leaves the ticket open on its own; pass
reject: true to close it with your feedback as the recorded reason. Two
constraints on rejecting, worth checking before the call:
- Agent-executed tickets can't be rejected over MCP — reject those in the web UI.
- Tickets already
donecan't be rejected — leave feedback withoutreject; it still reaches the generator.
Reading the thread
get_comments returns agent and human entries merged, newest first. Each entry
carries source (agent for anything written over MCP, user for a comment
typed in the Cogny UI) and type (comment, or feedback for an
add_ticket_feedback entry, which also carries verdict).
Organizational Context
A hierarchical knowledge graph for company strategy, competitor intel, and team knowledge.
| Tool | Description | Safety |
|---|---|---|
browse_context_tree | List child nodes at a path (or root categories) | Read-only |
read_context_node | Read full node content with backlinks | Read-only |
search_context | Full-text search across the context tree | Read-only |
get_context_tree_overview | High-level structure overview | Read-only |
write_context_node | Create or update a context node (upsert) | Write |
archive_context_node | Soft-delete a context node | Destructive |
Example prompt: "What do we know about our competitors' ad strategies?"
Connected Platforms
Cogny federates tools from your connected ad platforms. These appear as namespaced tools (e.g., mcp__google_ads__execute_gaql) and vary based on your connected integrations.
Supported platforms include Google Ads, Meta Ads, LinkedIn Ads, Search Console, and more. Every integration's full tool list is at cogny.com/integrations/tools.
| Tool | Description | Safety |
|---|---|---|
list_integrations | Available and connected integrations; connected ones include their server_id | Read-only |
add_custom_mcp_server | Register your own MCP server (name, https URL, optional API key sent as Authorization: Bearer). Discovers its tools and returns server_id plus each tool's read_only flag. Owners and admins only | Write |
refresh_mcp_discovery | Re-list a server's tools after it changes | Write |
Automations
Scheduled agents that act through write tools you greenlight. Every run is a ticket with a full transcript. Automations are included with Cloud. If these tools are not listed, automations aren't switched on for this workspace; contact support.
| Tool | Description | Safety |
|---|---|---|
list_automations | Automations with schedule, timezone, grants and the exact pre-approved tool list each run gets | Read-only |
create_automation | Name, instructions, crontab, IANA timezone (default Europe/Stockholm), write-tool action_grants with optional pinned constraints, optional explicit read_tools. Created disabled unless you enable it | Write |
update_automation | Change any of those fields; grant and read-tool lists are replaced as a whole. Enabling requires a crontab | Write |
run_automation | Run now, with or without a schedule. dry_run: true (the default) runs with no write authority | Write |
get_automation_run | Status, error and condensed transcript of a run, by ticket id | Read-only |
To point an automation at your own app, see Connect your own app to Cogny automations.
Workspace Status
| Tool | Description | Safety |
|---|---|---|
cogny_status | Check subscription, connected channels, and features | Read-only |
Bugs, Feature Requests and Support
Your agent can reach the Cogny team directly, with the details it already has, instead of you retyping them somewhere else. Each filing returns a reference, and the answer arrives in the Cogny app (the life-buoy icon in the header), with an email if you haven't read it within a day. A request for a platform Cogny doesn't connect to yet is researched on the spot instead, and the verdict usually comes back in the same call.
| Tool | Description | Safety |
|---|---|---|
report_bug | A tool errored, returned wrong data, or didn't do what its description says. Pass the tool name and the raw error. Clearly scoped bugs are fixed by Cogny's coding agent and ship after human review | Write |
request_feature | A capability Cogny doesn't have: usually a tool missing from a connected integration, or a new platform. For an existing integration, the request is checked against the platform's API, and buildable ones go to Cogny's coding agent. Start a new chat or reconnect once it ships to see the new tool | Write |
contact_support | A message to a person on the Cogny team: billing, account, anything that isn't a bug or a missing feature. Available even without an active subscription | Write |
A workspace can file up to 10 of these per 24 hours.
Authentication
Cogny uses OAuth 2.1 with authorization code flow and PKCE. When you add Cogny as a connector, your MCP client handles the OAuth flow automatically — you just sign in with your Cogny account.
Scopes: Access is scoped to your warehouse. You can only query data, reports, and tickets belonging to workspaces you're a member of.
Token refresh: Access tokens are short-lived and automatically refreshed by your MCP client.
Subscription Tiers
The tools available depend on your Cogny plan:
| Feature | Free, Solo, Cogny AI, Cogny Pro | Cloud |
|---|---|---|
| Connected platforms (Google Ads, Meta Ads, Shopify, ...), read and write | Full | Full |
| Context Tree | 50 nodes | Unlimited |
| Findings and task queue | Full | - |
| Growth Tickets | - | Full |
| BigQuery | - | Full |
| Reports & Charts | - | Full |
| Workspace Status, bugs, feature requests, support | Full | Full |
Every plan reaches the tools of the platforms you connect, with the same read and write tools on a $9 Solo plan as on Cloud. Cloud adds the BigQuery warehouse, reports and growth tickets. On Free, tool calls count against the 15 monthly MCP calls; on Solo, Cogny AI, Cogny Pro and Cloud they are unmetered under fair use (a burst guard of 100 calls per minute per workspace, answered with HTTP 429 and Retry-After).
When your own AI client calls a write tool over MCP, that client is the approval step: it asks you before running the tool, and Cogny executes the call it receives. To take a tool away from your agent altogether, set it to blocked under Settings → Integrations.
Evaluating Cogny for someone? The buying guide for agents covers plans, approvals, limits, billing and data protection, and Integrations and tools lists every tool of every integration with what it does and whether it reads or writes.
Troubleshooting
"Unknown tool" error
Your subscription tier may not include that tool. Use the cogny_status tool to check your workspace status and available features.
Authentication fails
- Ensure you're signing in with the email associated with your Cogny workspace
- Check that your workspace has an active subscription
- Try removing and re-adding the connector
No data returned from BigQuery
- Verify your BigQuery warehouse is connected in the Cogny dashboard
- Use
list_datasetsfirst to confirm available datasets - Check that your SQL query uses the correct dataset and table names
Connected platform tools missing
Connected platform tools only appear after you've linked the platform in your Cogny dashboard. Go to Settings > Integrations to connect Google Ads, Meta Ads, etc.
Timeouts on long queries
BigQuery queries are capped at 500 rows. If your query is timing out, add LIMIT clauses or narrow your date range.
Privacy & Security
- All data stays within your Cogny workspace — Cogny does not share data between workspaces
- BigQuery queries are read-only (SELECT/WITH only) — your data cannot be modified
- OAuth tokens are scoped per-user and per-workspace
- See our Privacy Policy for full details
Support
- Email: support@cogny.com
- Documentation: cogny.com/docs
Reading this with an AI agent? Fetch the raw markdown at /docs/mcp/index.md or see llms.txt.