> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognizo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Security & troubleshooting

> How your key is handled, and what to do when a tool call fails.

## 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.

<Warning>
  An assistant with your key can call the [write tools](/mcp/tools#writes) —
  creating brands, bulk-adding prompts, soft-deleting topics. Prefer a client
  that asks before each tool call.
</Warning>

Everything else about scope is the same as the REST API: only the public
surface, only your organization's brands. See
[Authentication](/guides/authentication#scope).

## Troubleshooting

<AccordionGroup>
  <Accordion title="The client shows no Cognizo tools at all">
    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.
  </Accordion>

  <Accordion title="Every tool call fails with 401">
    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:

      ```bash theme={null}
      curl https://core.cognizo.ai/api/v2/brands -H "X-API-KEY: YOUR_API_KEY"
      ```

      If that works and MCP doesn't, the client isn't sending the header.
  </Accordion>

  <Accordion title="A tool call fails with 403">
    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`.
  </Accordion>

  <Accordion title="Calls start failing with 429">
    You've hit the [rate limit](/guides/rate-limits) — 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.
  </Accordion>

  <Accordion title="The numbers don't match the dashboard">
    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](/guides/metrics).
  </Accordion>

  <Accordion title="The assistant invents a tool that doesn't exist">
    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](/mcp/tools) page.
  </Accordion>
</AccordionGroup>

## 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.