Skip to main content
Every MCP session acts for one person. The key’s scopes control whether it may write at all, and the person is recorded on every action for audit. A tool can only choose among the brands this connection was given, and the person always comes from the connection.

​
Auth context shape

When the server accepts your connection, it resolves a context that looks like:

​
Permissions

Every key carries a scope list, chosen when you mint it: read is the default. Calling a write tool with a read-only key returns a 403 with Insufficient scope — the check runs before the tool’s own logic, so nothing is written and no lookup happens. A key cannot do more than the person who created it. Creating a key with write needs the member, admin or owner role on the brand. A viewer’s key is read-only, and that is checked on every call, so a key loses write as soon as its creator becomes a viewer. Give an integration the narrowest scope that does its job. An agent that reports on visibility does not need write, and a read-only key cannot archive your tracked questions, launch paid ads or spend plan capacity if it leaks.
Keys created before permissions were enforced carry read + write, because that is the access they have actually had. Check the Permissions column in Settings → API Keys and re-mint any that should be read-only.

​
Transport options

​
stdio (self-hosted development)

Runs the MCP server as a local process against your own Citable database. It needs the same database credentials as the Citable backend, so it is not a way to connect to Citable’s hosted service. For that, use Streamable HTTP with an API key, including from Claude Desktop through the mcp-remote bridge (see the overview). Brand and user come from environment variables:
The process trusts these values. It does not check that the user is a member of the brand, and the session can read and write. Anyone who can start it already has direct access to the database, so a check inside it would not protect anything.

​
Streamable HTTP (remote agents)

Used by hosted agents and remote integrations. Auth is an API key in the Authorization header:
The key maps to a stored (brand, user, api_key) tuple. The resolved API key id is recorded on the auth context so every write is traceable back to a specific key.

​
API key lifecycle

Create API keys in the Citable web app under Settings → API Keys. Each key:
  • Belongs to one user (the creator) and one brand
  • Can be revoked anytime — revoked keys fail auth immediately
  • Stops working when its creator is removed from the brand or the brand is deleted
  • Records last_used_at on every successful call
Rotate by creating a new key, updating your integration, and revoking the old one. Keys are shown once at creation time and never displayed again. Treat them like any other secret.

​
Rate limits

Calls are limited to 60 per minute per API key (requests that arrive before auth resolves are bucketed by client IP instead). The limit is currently flat — it does not vary by plan tier, and it counts reads and writes together. Response headers tell you where you stand:
RateLimit-Reset is seconds until the window rolls over. Exceeding the limit returns a JSON-RPC error with Rate limit exceeded. If you need a higher limit for a specific integration, get in touch from your account.
Rate limiting is throughput protection, not an authorization control. Use the read scope to stop an integration from writing.