Developer docs

Connect an agent to your Brand DNA

The Jinn gateway is a single, read-only MCP endpoint. Point any MCP client at it with a bearer token and your agents can read your brand — voice, positioning, messaging, product, competitive playbook, and design system — before they generate a word.

Endpoint: https://app.jinn.works/api/mcp

Machine-readable spec: openapi.json — the same gateway described as OpenAPI, for agents and tooling that discover by spec.

The full developer guide, with per-client install instructions, now lives on the Jinn Agents docs page.Read the Agents developer docs →

Get a token

Start with Jinn Agents: connect your brand and Jinn extracts your Brand DNA — the record every Connected token reads. Tokens are self-serve — mint, rotate, and revoke them in your token panel. Every self-serve token is read-only and scoped to your own brand.

Your token is shown once, at creation. Store it in a secret manager and pass it as a bearer credential — treat it like a production API key, and never paste it back into an agent chat. Use of the API is governed by the API Terms.

Connect

Claude Code

Set JINN_MCP_TOKEN in your environment, then:

claude mcp add --transport http jinn https://app.jinn.works/api/mcp --header "Authorization: Bearer $JINN_MCP_TOKEN"

Cursor

One-click install — you paste your token into Cursor afterwards (the link never carries a real secret):

Add Jinn to Cursor →

Claude Desktop / any MCP client

Add to your client’s MCP config, replacing the placeholder with your token:

{
  "mcpServers": {
    "jinn": {
      "url": "https://app.jinn.works/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_JINN_MCP_TOKEN"
      }
    }
  }
}

Then have your agent call get_token_context — it reads back exactly which brands, scopes, and tier the token carries, so the agent knows what it can reach before it calls anything else.

Tool reference

A Connected token serves your brand across these tools. Brand-keyed tools take a slugand only resolve brands on your token’s allowlist — a brand you can’t access returns a generic brand not found (we never disclose whether a brand exists). Agency tokens serve the same tools across up to ten brands. Your tools/list always shows exactly what your token can call.

Tool	Returns
get_token_context	What your token can reach: brand slugs, scopes, audience, tier, subscription status, expiry, and a renewal_url. Call it first — no arguments. Read tier for your plan; audience is tool visibility and is "public" for every customer token.
get_brand_dna	Your full typed Brand DNA by slug — identity, story, archetype, positioning, audience, voice, messaging pillars, product, plus snapshot metadata.
get_brand_kit	Render-ready brand kit by slug — colors, fonts, logo, name, spacing.
get_brand_products	Your per-SKU product details by slug — name, description, category, form factor, ingredients, certifications, dimensions, weight, product URL. Empty products list means none captured yet.
get_brand_design_md	Your brand's DESIGN.md — an agent-readable design system — by slug.
get_brand_design_tokens	Design tokens as DTCG JSON by slug — colors, typography, spacing, radius, motion.
get_brand_dna_public	The bounded public Brand DNA projection by slug (identity, voice, positioning angle, messaging pillars, pain points, tribes). This is what demo tokens read.
ask_brand	A natural-language question about your brand in, the canonical facts that bear on it out — your agent writes the answer from them. Names the gaps your record can't answer so the agent says so instead of guessing. Question text is logged against the brand for its owner to review.
ping	Smoke test — verifies gateway wiring end-to-end. No arguments.

Auth model

The gateway is bearer-only. A token carries:

a scope — self-serve tokens are pinned to read(server-side; you can’t escalate it);
a brand allowlist — the sole authorization boundary for brand-keyed tools;
a tier (Connected / Brand / Agency). Your live subscription resolves the tier at request time, so the same bearer keeps working across trial → paid, renewals, and upgrades — no re-minting.

Rate limits

The API is limited to 120 requests per minute per token. Over the limit returns a rate-limited error with a retry hint — back off and retry. Limits may change; ceilings sit well above normal use, and we alert on anomalous volume rather than silently capping.

Error taxonomy

Errors carry a machine-readable code so an agent can branch without parsing prose. Auth failures happen before a tool runs and return one of:

code	Meaning
token_malformed	The bearer isn't a well-formed Jinn token. Fix the header; don't retry as-is.
token_invalid	No matching live token — the secret is wrong or was never issued.
token_revoked	The token was explicitly revoked. Mint a new one in the panel.
token_expired	The token or its subscription lapsed. The error carries a renewal_url — renew, then reconnect (see Renewal below).

Tool-call failures carry a kind (not_found, invalid_params, forbidden, rate_limited, upstream_unavailable, …) plus a retryable flag. Two are worth calling out:

TIER_REQUIRED

Calling a tool above your token’s tier returns a distinct TIER_REQUIREDerror (not a generic auth error, and not a hidden “unknown tool”). Its data carries required_tier and an upgrade_url — the exact upgrade path. Three tiers are live — Connected, Brand, and Agency — and a few tools need Brand or above (render-ready identity assets, for one), so a lower-tier token calling them gets exactly this error with the upgrade path attached.

token_expired & renewal

When a token expires — a trial ends, or a subscription lapses — verification returns token_expired with a renewal_url scoped to your brand. Renewing does not require a new token: your bearer survives trial-to-paid conversion, renewals, and tier upgrades, because the tier and entitlement are resolved from your live subscription on every request. A renewed subscription rolls the expiry forward and the same bearer resumes working.

Token hygiene

Shown once. A secret is displayed only at mint or rotation — capture it then.
Rotate with overlap. Rotating mints a new token and keeps the old one valid for a short overlap window (default 24h), so you can swap it into your agents with no downtime before it expires.
Revoke instantly. Explicit revoke takes effect immediately.
Panel-only. Minting, rotating, and revoking happen in the web panel — never over an MCP tool call, so a plaintext secret never lands in an agent transcript.
Multiple named tokens per brand are supported — issue one per agent for revocation granularity.

Auth roadmap

Today the gateway is bearer-only. There’s intentionally no .well-known/oauth-protected-resource— that’s an OAuth-discovery mechanism and would be meaningless without an authorization server. OAuth (for claude.ai / Claude Desktop custom connectors) lands with the Jinn account platform, via WorkOS AuthKit — the same token interface, an added front door.