> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stratta.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP overview

> How the Stratta MCP server authenticates, resolves your key, and exposes its tools.

The Stratta MCP server (`@stratta/mcp`) connects your Claude client to your Stratta workspace. It
speaks the [Model Context Protocol](https://modelcontextprotocol.io) over stdio and exposes
**18 tools**: 8 for reading norms and 10 for ingesting them.

|                |                                                              |
| -------------- | ------------------------------------------------------------ |
| Package        | [`@stratta/mcp`](https://www.npmjs.com/package/@stratta/mcp) |
| Binary         | `stratta-mcp`                                                |
| Transport      | stdio                                                        |
| Runtime        | Node.js ≥ 20                                                 |
| Authentication | API key (`sk_strt_…`)                                        |

## Authentication

Every tool call is authenticated with your API key. The server validates the key against the
Stratta backend, resolves it to your **user** and **organization**, and scopes all reads and
writes accordingly. The organization is derived from the key — it is never a parameter a client
can set.

### How your key is resolved

The server looks for your key in this order and uses the first it finds:

<Steps>
  <Step title="STRATTA_API_KEY environment variable">
    If set, it takes precedence. Best for ephemeral or CI-style usage.
  </Step>

  <Step title="~/.stratta/config.json">
    Written by `npx -y @stratta/mcp login` or the first-use prompt. Stored owner-only (mode `0600`):

    ```json theme={null}
    { "apiKey": "sk_strt_xxx" }
    ```
  </Step>

  <Step title="First-use prompt (elicitation)">
    If no key is found and your client supports it, the server asks for the key on the first tool
    call, validates it, and saves it to the config file.
  </Step>
</Steps>

### Environment variables

<ParamField path="STRATTA_API_KEY" type="string">
  Your API key from [stratta.ch/api-keys](https://stratta.ch/api-keys). Optional: if unset, the
  server falls back to `~/.stratta/config.json` or prompts on first use.
</ParamField>

<ParamField path="STRATTA_CONVEX_URL" type="string" default="Stratta production backend">
  Override the backend URL. Only needed if you self-host Stratta.
</ParamField>

## How Claude uses the tools

Claude is guided to navigate norms in a deterministic order so that every answer is backed by a
real citation:

<Steps>
  <Step title="get_methodology">
    The mandatory first call — loads the persona, navigation rules, and citation format.
  </Step>

  <Step title="list_norms">
    See which norms are available in your workspace.
  </Step>

  <Step title="get_toc → get_subtree">
    Open the table of contents and drill into the relevant chapter.
  </Step>

  <Step title="get_section">
    Read the full content of a section (text, formulas, tables, figures, cross-refs).
  </Step>

  <Step title="get_cross_refs → get_section">
    Follow links to other norms and read those too, for compound questions.
  </Step>

  <Step title="get_figure">
    Retrieve a diagram when the answer depends on it.
  </Step>
</Steps>

Use `search_in_norm` whenever the section path is unknown.

## Usage tracking

After each successful tool call, the server records a usage event (tool name, status, duration)
against your key. This powers your dashboard stats and future billing. Tracking happens only
after authentication and uses the key as proof of possession — usage can't be attributed to
someone else's key.

## Tool reference

<CardGroup cols={2}>
  <Card title="Read tools" icon="book-open" href="/en/mcp/read-tools">
    The 8 tools Claude uses to query norms.
  </Card>

  <Card title="Ingestion tools" icon="file-arrow-up" href="/en/mcp/ingestion-tools">
    The 10 `ingest_*` tools that write norms.
  </Card>
</CardGroup>