Skip to main content

​
How your key is handled

Your API key is sent by your client, on every request, over TLS. The MCP server reads it from the X-API-KEY header, attaches it to the upstream API call, and forgets it when the request ends. It is never persisted, and the server holds no credentials of its own — it can’t call the API without a key you supplied. That has three practical consequences:
  • The key lives in your client’s config. Whoever can read that file (or that machine) can act as your organization. Treat it like an SSH key.
  • Revoking is instant and total. Delete the key in the dashboard and the next tool call fails with 401 — no session to expire, no cache to wait out.
  • One key per client keeps that blast radius small. Revoke a laptop without breaking your CI integration.
An assistant with your key can call the write tools — creating brands, bulk-adding prompts, soft-deleting topics. Prefer a client that asks before each tool call.
Everything else about scope is the same as the REST API: only the public surface, only your organization’s brands. See Authentication.

​
Troubleshooting

Almost always a transport or header problem, not an auth one — the server lists its tools before any key is checked.
  • The URL must end in /mcp: https://mcp.cognizo.ai/mcp.
  • The transport must be Streamable HTTP (sometimes labelled “HTTP”), not SSE and not stdio.
  • Restart the client after editing its config — most read MCP config only at startup.
The key isn’t reaching the API, or it isn’t valid.
  • Check the header name is exactly X-API-KEY.
  • Check the value has no Bearer prefix and no stray quotes or trailing whitespace — copy-paste from a terminal is a common culprit.
  • Confirm the key still exists in the dashboard and hasn’t expired or been revoked.
  • Test the same key straight against the API:
    If that works and MCP doesn’t, the client isn’t sending the header.
The key is valid but the request is out of scope: a brand another organization owns, or an endpoint outside the public API surface. Ask the assistant which brand id it used and check it against list_brands.
You’ve hit the rate limit — 600 requests per minute per key. An assistant looping over prompts one call at a time can get there. Ask it to use a list tool with page_size up to 100 instead of fetching rows individually, and wait a minute before retrying.
Usually a window mismatch. The workflow tools use the API default — the last 30 days — while the app may be showing a different range, and the ads endpoints default to 90 days. Ask the assistant to pass explicit filter[ran_at_start] / filter[ran_at_end] values.If sentiment looks wrong, check the unit: it’s a 1–100 average, not a percentage. See Metrics & units.
Tool names mirror the API’s operation ids exactly (list_brand_prompts, get_brand_visibility, …). If your client reports an unknown tool, it’s working from a stale tool list — reconnect the server. The current list is on the Tools page.

​
Still stuck

Get in touch with the failing tool name, the approximate timestamp, and the first few characters of the key (cog_sk_… — never the whole thing). That’s enough to trace the request without exposing the secret.