Quickstart

ClariLayer is a personal context layer for your AI coding agent, delivered over MCP. You install it once into Claude Code, Cursor, or Codex, and from then on 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. You will mint a context key, install the MCP server, confirm the connection, and then 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 over OAuth (sign in & approve), with no key to copy. Either way, ClariLayer never holds your warehouse credentials and never runs your SQL — your agent stays the connector to your data.

1. Mint a context key

In ClariLayer, create a context key. 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.

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; claude.ai is a UI flow — paste the MCP URL into Connectors and approve. Each CLI snippet is generated from the same install helper the in-app "Connect your AI" screen uses, so what you see here is exactly what the product ships.

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

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

{
  "mcpServers": {
    "clarilayer": {
      "url": "https://clarilayer.com/api/mcp/mcp",
      "headers": {
        "Authorization": "Bearer cl_YOUR_CONTEXT_KEY"
      }
    }
  }
}

[mcp_servers.clarilayer]
url = "https://clarilayer.com/api/mcp/mcp"
http_headers = { "Authorization" = "Bearer cl_YOUR_CONTEXT_KEY" }

# Older Codex without direct-HTTP support: comment out the two
# lines above and uncomment the two below (this route needs
# Node.js / npx installed):
# command = "npx"
# args = ["-y", "mcp-remote", "https://clarilayer.com/api/mcp/mcp", "--header", "Authorization: Bearer cl_YOUR_CONTEXT_KEY"]

## ClariLayer — your data context layer (use it proactively)

ClariLayer is connected over MCP and holds this project's durable data context: definitions, schema notes, reusable SQL, assumptions, caveats, and decisions. Use it WITHOUT waiting to be asked.

- Bootstrap once, from files: to ground a fresh store, call `bootstrap` with the content of files the user already has — SQL, dbt models, `CLAUDE.md` / notes, or a codebook / data dictionary (mapped into the `dictionary` source's rows). YOU read and supply that file content; ClariLayer never connects to or reads the warehouse — it feeds on files, never the data.
- Recall first: before writing SQL, defining or computing a metric, or answering a question about this data, call `get_analysis_context` (pass a `use_case`). Build on what is already known instead of re-deriving it. Recall returns display-capped previews — when you need an entry's full stored content (its complete body or saved SQL), fetch it with `get_context_entry` (type + name).
- Write back as you learn: when you establish a durable fact — a definition, schema note, reusable query (attach the SELECT as `sql`), assumption, caveat, or decision — save it with `remember`. Use `propose` for suggestions (they go to the human's review inbox).
- Harvest only when asked: if (and only if) the user asks you to learn from this conversation, stage the durable facts via ONE `propose_batch` call with `provenance: "agent"` and review them in the Inbox — never ambiently, never auto-accepted; the raw transcript is never sent, only the distilled candidates.
- Reconcile on drift: if a definition's SQL changed or staleness is flagged, call `reconcile` to check it against the warehouse.
- Stay honest: treat status as `asserted`/`caveat`, never `verified`.

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, ask your agent to call the clarilayer__health tool. For an authenticated key it returns { ok: true, user, org }, which confirms the transport and your key end to end. If you get an authentication error, re-check that you pasted the full cl_… secret and that the key has not been revoked.

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: point your agent at your existing SQL files, a data dictionary or codebook, dbt models, or a CLAUDE.md, and it sends the content to the bootstrap tool. Your SQL is validated and deterministically structured, a data dictionary maps into one schema-note per variable, and your dbt models and notes are stored so they can be recalled later.

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.

The four verbs

After connecting, your agent has four context tools. Each has its own page:

• bootstrap — bulk-ingest your existing SQL, a data dictionary / codebook, dbt, and CLAUDE.md 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 definition against your real warehouse result; a mismatch is flagged as a caveat.

Beyond the four verbs

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

• 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, a declared-vs-actual mismatch is flagged as a caveat; otherwise the entry stays asserted. Today those are the only two outcomes — ClariLayer does not stamp an entry as verified yet. 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.