Skip to main content

​
How your credentials are handled

Whichever way you connect, the credential is sent by your client, on every request, over TLS. The MCP server 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 something you supplied.

​
If you signed in (Claude web, desktop, mobile, Cowork)

Claude holds a short-lived token issued by Cognizo, refreshes it as needed, and sends it as a bearer token. You never see or store it.
  • Revoke from either end. Disconnect the connector in Claude, or revoke the authorization in Cognizo.
  • Tokens are short-lived and refreshed automatically. A revoked authorization stops working within minutes rather than instantly — the refresh is what fails.
  • The organization is fixed at sign-in. To read a different one, reconnect and pick it on the consent screen.

​
If you used an API key

The server reads it from the X-API-KEY header and forwards it upstream. 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.
A connected assistant can call the write tools — creating brands, bulk-adding prompts, soft-deleting topics, generating articles and recomputing opportunities. The last two spend quota. 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

In Claude Code, Cursor, VS Code, Windsurf or ChatGPT this is 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 connector authorized but the token can’t reach your data. Usually the organization: the consent screen’s selector decides which one the connector reads, and picking the wrong one gives a valid token with no access to the brands you expect.Disconnect the connector, add it again, and check the organization on the consent screen. Ask the assistant to run list_brands first — if it returns a different set than the dashboard, that’s the mismatch.
Cognizo is an official connector, so there’s no URL, header or client id to get wrong.
  • Go straight to claude.ai/directory/cognizo, or look under Browse connectors — not “Add custom connector”.
  • An old custom connector gets in the way. If you added https://mcp.cognizo.ai/mcp by hand before, disconnect and remove it, then add the official connector.
  • If Connect itself fails, it stopped at sign-in rather than discovery. Retry it: you should land on the Cognizo sign-in page and then a consent screen with an organization selector.
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 at app.cognizo.ai/api-keys 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.
Three things go wrong, in this order of likelihood:
  • Developer mode is off. Custom MCP servers don’t appear at all without it. See OpenAI’s developer mode guide.
  • The app wasn’t selected in the conversation. Pick it from the developer-mode menu before asking — the tools aren’t there otherwise.
  • The header is misconfigured. Authentication must be an access token / API key with header scheme Custom header and header name exactly X-API-KEY. A Bearer prefix on the value will fail.
On Business and Enterprise plans, adding the app may require a workspace admin.
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 and the approximate timestamp. If you’re using an API key, include its first few characters (cog_sk_… — never the whole thing); if you signed in, say which organization you picked. That’s enough to trace the request without exposing anything secret.