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

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 a Brand DNA report: we extract your Brand DNA and issue a 30-day Connected token. After that, 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.
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.
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 cannot escalate it);
a brand allowlist - the sole authorization boundary for brand-keyed tools;
a tier (Connected / 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 is not a well-formed Jinn token. Fix the header; do not 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 path to unlock it. At launch a single Connected tier serves the full surface, so you will rarely see this; the machinery is in place for future tiering.

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