Quickstart

ClariLayer is a personal context layer for your AI agent, delivered over MCP. Connect it once to Claude Code, Cursor, Codex, or claude.ai, and your agent stops re-learning your data every session: it can recall the definitions, schema notes, joins, and gotchas you have saved, so it stops making the same mistakes — wrong table, wrong join, refunds counted in revenue.

This Quickstart gets you from zero to a connected agent in a few minutes. For Claude Code, Cursor, or Codex, you will mint a context key and install the MCP server. For claude.ai, you will connect the production server through OAuth instead. Then you will confirm the connection and bootstrap your first context so your agent has something real to ground on.

What you need

• An MCP client: an AI coding agent (Claude Code, Cursor, or Codex), or claude.ai itself via its Connectors UI.
• A ClariLayer workspace. The CLI agents authenticate with a context key you mint; claude.ai connects to ClariLayer's production server over OAuth (sign in and approve), with no key to copy. Other or self-hosted deployments must enable and configure OAuth before they can offer that flow. Either way, ClariLayer never holds your warehouse or CRM credentials and never runs your SQL or calls the CRM provider — your agent stays the connector to your data.

1. For CLI agents, mint a context key

If you are connecting Claude Code, Cursor, or Codex, create a context key in ClariLayer. A context key is a cl_… secret that authenticates your agent to the MCP server. It carries context:read (so your agent can recall) and context:write (so it can remember, bootstrap, and reconcile). The full secret is shown exactly once at creation, so copy it immediately and keep it out of tickets, prompts, and screen recordings.

Keys are scoped to you. A read-only key can only call the read tools; the write tools require context:write.

If you are connecting claude.ai to ClariLayer's production server, skip this step. Its Connectors flow uses OAuth and has no context-key field.

2. Install the MCP server

ClariLayer's MCP server is a remote, stateless HTTP endpoint at POST /api/mcp/mcp. Pick your client below. The CLI agents (Claude Code, Cursor, Codex) take a copy-paste command with a context key; on the production server, claude.ai is a UI flow — paste the MCP URL into Connectors, then sign in and approve. An operator running another deployment must enable and configure its OAuth issuer and key discovery before claude.ai can use the same flow.

For each CLI agent, the selector also provides a client-specific prompt for installing or updating ClariLayer's managed project instructions. The connection command and managed prompt are generated from the same canonical helpers the in-app "Connect your AI" screen uses.

https://app.clarilayer.com/api/mcp/mcp

claude mcp add --transport http clarilayer https://app.clarilayer.com/api/mcp/mcp --header "Authorization: Bearer cl_YOUR_CONTEXT_KEY"

Install or update ClariLayer's managed instructions for Claude Code.

ClariLayer's browser and remote MCP server have not edited any local file. You are the local agent performing this repository-local inspection and, only after approval, the edit.

1. Call the ClariLayer MCP tool `get_project_stanza`. Use its structured `managed_block`, `legacy_stanza`, `append_once_sentinel`, `client_targets`, and `managed_apply_guidance` fields exactly; do not recreate or paraphrase their contents.
2. Select only the `claude-code` descriptor and confirm that it names exactly `CLAUDE.md`. If the descriptor or the pinned metadata below differs, change nothing and report `conflict/manual review`.
3. Inspect exactly `CLAUDE.md`. Do not inspect or modify any other project instruction target.
4. This selected target has no required preamble.
5. If the selected target is already byte-identical to the current managed form, change nothing and report `already current`.
6. If an install or safe update is available, explain the one-file change and ask for my explicit approval before editing. If approval is declined, stop without claiming a terminal installation state.
7. After approval, follow the canonical fail-safe guidance below. Preserve every byte outside a recognized managed range or the byte-identical legacy block. Never append over an edited legacy sentinel, malformed markers, or incompatible frontmatter.
8. Translate the canonical guidance's internal `already-current` label to `already current`, and `conflict/manual-review` to `conflict/manual review`. After an approved create or replacement, report `installed`. Report exactly one of these user-facing terminal states with no alternate spelling: `installed`, `already current`, `conflict/manual review`.

Selected target: CLAUDE.md
Managed protocol version: 1
Managed payload hash: sha256:f10ebe7fb80f2db2e2bc31671488c7ab18530bd9e6bbf716c590bf8a95199cc4
Managed begin marker: <!-- BEGIN CLARILAYER MANAGED INSTRUCTIONS -->
Managed end marker: <!-- END CLARILAYER MANAGED INSTRUCTIONS -->
This target has no required preamble. Do not invent one.

Canonical fail-safe guidance:
Select exactly one client target; never touch more than one instruction file. For Cursor, if the selected target already exists, require its exact required_preamble before any already-current, append, or replacement decision; otherwise return conflict/manual-review and change nothing. If that target contains exactly one well-formed managed range with the published begin marker before the end marker, compare the entire range: when it is byte-identical to managed_block return already-current and change nothing; when it is older or different replace only that marked range. Duplicate, nested, reversed, or unmatched markers are conflict/manual-review: change nothing. With no managed marker, replace only a byte-identical legacy_stanza. If append_once_sentinel exists but the full legacy bytes differ, return conflict/manual-review and change nothing. If neither markers nor the legacy sentinel exists, append managed_block to an existing Claude Code or Codex target, or create the selected target. For Cursor, create the target with its exact required_preamble, a blank line, then managed_block. Never edit bytes outside the recognized managed range or exact legacy block, never delete unrelated content, and never claim the server or browser edited a file.

Recover one older shortened ClariLayer section in Claude Code's project instructions.

This is a separate, opt-in guided legacy migration. The normal managed installer must remain fail closed for edited legacy text. ClariLayer's browser and remote MCP server have not read or edited this repository; you are the selected local agent, and only you may inspect or change the one target below after explicit approval.

Follow this algorithm exactly:

1. Call the ClariLayer MCP tool `get_project_stanza`. Use its structured `managed_block`, `managed_version`, `managed_hash`, `managed_markers`, and `client_targets` fields exactly; never recreate, paraphrase, or partially copy `managed_block`. Select only the `claude-code` descriptor. Require its `client` to be `claude-code`, its `target_file` to be `CLAUDE.md`, and its `required_preamble` to be null. Require all returned version, hash, and marker metadata to match the pinned values below, and require `managed_block` to carry those exact markers and metadata. Any mismatch is unsafe.
2. Read the entire byte content of exactly `CLAUDE.md`. Do not inspect or modify any other project instruction target. The browser and remote server have not performed this read or any write.
3. Recovery is eligible only if every condition below is true:
   - No managed begin marker or managed end marker occurs anywhere in the file.
   - The exact line `## ClariLayer — your data context layer (use it proactively)` occurs exactly once in the whole file, and that sole occurrence is a real Markdown H2 heading outside every backtick or tilde fenced code block. Heading-shaped text inside fenced code is not eligible.
   - The candidate section is unambiguously bounded from the first byte of that H2 heading through immediately before the next real Markdown H1 or H2 heading outside fenced code, or through EOF when no later H1/H2 exists.
   - Preserve the exact separator at that boundary instead of consuming it. Before a following heading, take the maximal contiguous whitespace-byte suffix immediately preceding that heading, require it to contain at least one complete line ending, and keep that suffix outside the replacement range so the following heading remains at the start of its original line. At EOF, likewise keep any maximal trailing whitespace-byte suffix that contains the file's final line ending outside the replacement range; if there is no final line ending, preserve the no-trailing-newline state. These preserved bytes are not part of `managed_block` and must not be normalized.
4. Fail closed on any unsafe state. A missing or duplicate exact heading, a heading that exists only inside fenced code, an unterminated or ambiguous fence, an ambiguous section boundary or boundary separator, any complete/malformed/partial/duplicate/nested/reversed managed marker, any selected-target or pinned-metadata mismatch, or any other uncertainty means: change nothing, report `conflict/manual review`, and recommend manual review. Never append `managed_block` over the legacy section.
5. Before writing, show the exact full one-file replacement diff for `CLAUDE.md`: the complete bounded candidate replacement range removed and the complete canonical `managed_block` added, while every preserved boundary or trailing suffix byte appears as unchanged context, with no elision, summary, or truncation. Ask for explicit approval of that exact diff. If approval is declined, write nothing and claim no terminal installation state.
6. Immediately before any approved write, re-read the whole file as bytes and require byte-for-byte equality, including line endings, with the bytes used to produce the shown diff. If any byte changed concurrently, stop without writing and report `conflict/manual review`.
7. After approval, replace only the bounded candidate replacement range with the returned canonical `managed_block`. Preserve every byte before and after that range, including the exact boundary/trailing suffix isolated in step 3, unrelated content, whitespace, line endings, and the existing trailing-newline state. Never synthesize a separator by altering `managed_block`; retain the original separator outside it. Do not modify another instruction target.
8. Re-read the whole target after the write. Verify that the inserted managed range is byte-identical to `managed_block`; the pinned begin and end markers each occur exactly once and in that order; the installed version and hash match both the returned and pinned values; the exact old heading is gone; and every byte outside the replaced range is unchanged. Only after every check passes, report the existing terminal state `installed` and a separate supplemental receipt/detail exactly `guided legacy migration`. Do not create a new terminal state. If any verification fails, report it honestly and never call the result `installed`.

Selected recovery client: claude-code
Selected target: CLAUDE.md
Required preamble: null
Exact legacy H2: ## ClariLayer — your data context layer (use it proactively)
Managed protocol version: 1
Managed payload hash: sha256:f10ebe7fb80f2db2e2bc31671488c7ab18530bd9e6bbf716c590bf8a95199cc4
Managed begin marker: <!-- BEGIN CLARILAYER MANAGED INSTRUCTIONS -->
Managed end marker: <!-- END CLARILAYER MANAGED INSTRUCTIONS -->

The managed prompt names exactly one target for the client you selected. Copying it does not change your repository: your local agent inspects that one file, asks for approval before an edit, and preserves bytes outside the recognized ClariLayer range. An already-current or conflict decision, or an approved write, reports exactly installed, already current, or conflict/manual review; if you decline approval, the agent stops without claiming an installation state. A malformed managed range, a legacy stanza whose sentinel remains but whose full bytes differ, or incompatible Cursor frontmatter fails closed to manual review. For Claude Code and Codex, otherwise-unrecognized existing text is preserved while the managed range appends on first install.

If an early CLAUDE.md or AGENTS.md kept the exact old ClariLayer heading but shortened or edited the section underneath it, open Older shortened ClariLayer section? and explicitly copy the separate guided recovery prompt. The standard installer remains fail closed. The recovery option appears only for Claude Code and Codex, shows a full one-file replacement diff before asking for approval, and stops on ambiguous headings, fenced examples, marker fragments, or concurrent file changes. Cursor recovery stays manual because its frontmatter and target semantics differ. Neither copying option lets the browser or remote server read or write your repository.

For the three CLI agents the endpoint and the Authorization: Bearer cl_… header are identical — only the config format differs. Claude Code takes the URL as a positional argument with --transport http; Cursor and Codex take the same URL plus the Authorization header in their own MCP config. claude.ai is different: it has no API-key field and connects over OAuth, so you paste only the URL and then sign in & approve — there is no context key for that path.

3. Confirm the connection

Once the server is registered and authentication is complete, ask your agent to call the clarilayer__health tool. It returns { ok: true, user, org }, which confirms the transport and authenticated workspace end to end. For a CLI authentication error, re-check that you pasted the full cl_… secret and that the key has not been revoked. For claude.ai, reconnect and complete the OAuth approval flow.

4. Bootstrap your first context

A fresh context store is empty, so your agent has nothing to recall yet. The fastest way to get day-1 value is to bootstrap from artifacts you already have: SQL, dbt models, a CLAUDE.md or freeform notes, a data dictionary or codebook, and semantic-layer models are the five supported source kinds. Your agent reads or normalizes those artifacts and sends only the chosen artifact content or structured model rows to the bootstrap tool.

Try a prompt like: "Bootstrap my ClariLayer context from ./analytics/sql and my dbt models." Then ask your agent to recall something — "What does ClariLayer have on active customers?" — and you should see your own definitions come back, each tagged with its provenance and status. For the recall-first working loop that keeps your agent grounded once it is connected, follow the full guide to agent context.

5. Finish relevant data work with a receipt

The managed instructions establish a completion loop: recall → confirmed live remember/reconcile → context_checkpoint. Your agent recalls before relevant data work, writes a confirmed durable change to live context with remember, and reconciles it when appropriate. If the suggestion still needs human review, it uses propose and stops for acceptance; proposal-only work cannot continue to a completion receipt. After an accepted proposal is live, or after another confirmed live outcome, the completion loop can continue.

A pending proposal is not live recall context, and an update_failed checkpoint does not allow completion. When the task made no durable context change, the agent can use no_update_required only after explicitly checking the relevant facets.

The receipt has a deliberately narrow meaning: it persists the agent's managed-protocol declaration (context_updated or no_update_required) and validates ownership and eligibility of any referenced ClariLayer objects. It does not independently prove that an entry changed during this task, that code deployed, that Databricks validation passed, that a query result is correct, or that the saved rule is semantically equivalent to an external system.

The four verbs

After connecting, your agent has four headline, everyday verbs. Each has its own page:

• bootstrap — bulk-ingest SQL, dbt, CLAUDE.md notes, a data dictionary / codebook, and semantic-layer models so you do not start from a blank store.
• recall — pull the most relevant saved context for the current task, in-flow (get_analysis_context).
• remember — save a definition, schema note, join, or gotcha so your agent retains it across sessions.
• reconcile — check a saved SQL definition against warehouse actual_sample evidence or a HubSpot CRM contract against row-free crm_evidence; a mismatch is flagged as a caveat. Salesforce contracts remain store/recall-only.

Beyond the four verbs

The four verbs above are the everyday surface. As you go deeper, the agent can also:

• Record a completion receipt — after the relevant recall and confirmed write/reconcile path, call context_checkpoint so the task has a durable context_updated or no_update_required receipt.
• Harvest a whole session — on your explicit request, distill the durable facts from a working conversation and stage them in your Context Inbox for review (via propose / propose_batch). Nothing is auto-saved; you approve each, and the transcript is never sent to ClariLayer — only the distilled candidate facts.
• Manage what's saved — reversibly retire context with archive / restore (and archive_reasoning / restore_reasoning for the caveats and assumptions attached to an entry), or remove it for good with forget.

What "checked" means

ClariLayer is a trust product, so it is precise about what it can stand behind. When reconcile runs against a supported warehouse or HubSpot evidence path, a declared-vs-observed mismatch is flagged as a caveat; otherwise the entry stays asserted. Those are the only public outcomes. The verified status remains gated and is not live. Read Verified vs Asserted for exactly what each status means and why.

Where to go next

• The Context Layer explains the mental model: why a personal, reconciled, in-flow context layer beats a hand-typed CLAUDE.md.
• AI Agent Context Guide shows the recall-first working loop in practice.
• SaaS Metrics Definition Library is a reference for the metric definitions teams argue about most.
• The For teams strand covers what happens as your personal context merges into shared, governed team context.