[!IMPORTANT] Your STRATTA_API_KEY is a secret — it grants read/write access to your Stratta workspace. Never commit it to a repository, paste it into a shared/ project-scoped MCP config, or share it in logs. Prefer a user-scoped config or a shell environment variable. If a key leaks, revoke it immediately at https://stratta.ch/api-keys.

Do you need this package?

Often not. Stratta also runs as a remote connector — one address, a browser sign-in, no key and no Node:

https://stratta.ch/mcp

That is the shorter path, and the only one that works in an agent running in the cloud (claude.ai). See https://stratta.ch/docs/en/guides/connect-remote.

This package is what you want when:

you are ingesting a norm — it reads a PDF from your disk and runs a Python pre-pass, neither of which a remote connector can reach;
your agent cannot open a browser — CI, a scheduled task, a server;
you would simply rather run the server yourself.

Install

Claude Code (recommended)

Add the server — no key needed up front:

claude mcp add stratta --scope user -- npx -y @stratta/mcp

--scope user registers it for your user, so the tools are there in every project. Without it, claude mcp add writes to the current folder's config and the server exists nowhere else.

Then sign in. This opens stratta.ch in your browser, where you confirm which machine and organisation to authorise; the key comes back to the terminal on its own and is saved to ~/.stratta/config.json (owner-only, 0600). You never see it, and you only do this once:

npx -y @stratta/mcp login

No browser on this machine — remote server, SSH, CI? login --paste asks for a key from https://stratta.ch/api-keys instead, without echoing it.

If you skip the step entirely, Claude Code prompts you for a key on the first tool call.

You can also pass the key explicitly as an environment variable (it then takes precedence over the saved key):

claude mcp add stratta --scope user --env STRATTA_API_KEY=sk_strt_xxx -- npx -y @stratta/mcp

Commands

Command	Purpose
`npx -y @stratta/mcp login`	Authorise this machine from your browser
`npx -y @stratta/mcp login --paste`	Paste a key, when there is no browser
`npx -y @stratta/mcp logout`	Remove the key stored on this machine
`npx -y @stratta/mcp whoami`	Which account and workspace this machine speaks as
`npx -y @stratta/mcp doctor`	Diagnose an install that is not responding
`npx -y @stratta/mcp update`	Check your version and fetch the latest
`npx -y @stratta/mcp --help`	All of the above

Run doctor first when norms are missing: a revoked key, a stale STRATTA_API_KEY in your shell and an unreachable backend all look identical from inside the agent, and are fixed differently.

Staying up to date

npx -y @stratta/mcp fetches the published package, but npx caches what it resolved, so a server can keep launching a version npm replaced weeks ago with nothing to tell you.

npx -y @stratta/mcp update

Prints the version you are running and the one npm serves, and fetches the new one if they differ. Restart your agent afterwards. The server also mentions it on stderr at startup when it notices it is behind.

Claude Desktop

npx -y @stratta/mcp login

Then add the server to claude_desktop_config.json (Settings → Developer → Edit Config) — no key needed in the file:

{
  "mcpServers": {
    "stratta": {
      "command": "npx",
      "args": ["-y", "@stratta/mcp"]
    }
  }
}

Restart Claude Desktop. The Stratta tools should appear in the MCP indicator.

Prefer to keep the key in the config instead of ~/.stratta/config.json? Add an "env": { "STRATTA_API_KEY": "sk_strt_xxx" } block to the server entry — but that file then stores the key in plaintext, so keep it private and unsynced.

Global install (optional)

npm install -g @stratta/mcp

Then use "command": "stratta-mcp" instead of npx.

Configuration

The API key is resolved in this order: the STRATTA_API_KEY env var, then ~/.stratta/config.json (written by login or the first-run prompt). Other settings come from environment variables — see .env.example.

Variable	Required	Default	Purpose
`STRATTA_API_KEY`	no¹	–	API key from https://stratta.ch. ¹If unset, the server falls back to `~/.stratta/config.json`, or prompts you on first use (clients that support elicitation).
`STRATTA_CONVEX_URL`	no	Stratta prod backend	Override only if you self-host.

Tools exposed

Read (8 tools — query norms in your workspace):

Tool	Purpose
`get_methodology`	Behavioural contract: persona, workflow, meta-routing hints, answer rules. Call first.
`list_norms`	List all norms published in your workspace (code, year, title, language).
`get_toc`	Hierarchical TOC for a norm (default `maxDepth=1` = chapters).
`get_subtree`	Drill into a chapter/section subtree (`path` + `maxDepth`).
`get_section`	Full enriched content of a section (formulas, tables, figures, cross-refs).
`search_in_norm`	Keyword search inside a norm.
`get_figure`	Retrieve a figure inline (base64 ImageContent) + public URL.
`get_cross_refs`	Outgoing cross-refs from a section to other norms.

Dossier (7 tools — keep what was decided on a project):

Tool	Purpose
`list_dossiers`	Your organisation's dossiers, most recently touched first, with open-question counts.
`open_dossier`	Open a project's dossier, creating it if needed. Idempotent on the name.
`open_question`	Open one question to settle, with optional named options. Idempotent on the title.
`save_finding`	Record one piece of evidence: a cited article, a retained value and why, an observation.
`record_decision`	Settle a question with a decision the engineer has confirmed, and the retained option.
`load_dossier`	Reload everything: questions with their evidence and decisions, open ones first.
`resolve_question`	Close a question without a decision, or reopen one. The evidence stays.

A dossier is read, annotated, reviewed and exported from stratta.ch/dossiers.

Ingest (10 tools — add YOUR licensed norms; driven by the bundled ingest-norm skill):

Tool	Purpose
`ingest_status`	Check if a norm already exists in your workspace.
`ingest_create_document`	Create a draft norm document.
`ingest_create_sections`	Bulk-insert sections (returns `nodeId → sectionId` map).
`ingest_attach_formula`	Attach a LaTeX formula to a section.
`ingest_attach_table`	Attach a structured table `{headers, rows}` to a section.
`ingest_attach_cross_ref`	Attach an explicit cross-ref to another norm.
`ingest_upload_figure`	Upload a figure (base64 PNG/JPEG/WebP, ≤ 8 MB) to a section.
`ingest_normalize_cross_refs`	Auto-detect and rebuild cross-refs from section content.
`ingest_publish`	Flip a draft to published — visible via the read tools.
`ingest_delete`	Delete a document and all its children.

How agents should use it

For querying:

Call get_methodology first — load the behavioural contract.
Call list_norms to see what's available in your workspace.
Call get_toc(norm) to navigate the structure; get_subtree to drill in.
Call get_section(norm, path) to read specific content.
Use search_in_norm when the section path is unknown.
Follow crossRefs for compound questions (e.g. SIA 261 → SIA 263 → EC).
Call get_figure when the section references a figure relevant to the answer.

For ingesting your own licensed norms, see the bundled ingest-norm skill — a 2-phase hybrid pipeline (since 0.4.0): a Python pre-pass (scripts/ingest-prepass.py, PyMuPDF) extracts the hierarchical tree and rasterizes figures deterministically, then the agent enriches sections with summaries, LaTeX formulas, tables and cross-refs via targeted visual reading. Requires Python ≥ 3.10 with PyMuPDF (python -m pip install --user pymupdf).

Troubleshooting

`Authentication failed` / `Invalid API key`

Verify the key starts with sk_strt_ and is not revoked at https://stratta.ch/api-keys.
Check the env var is reaching the process: echo $STRATTA_API_KEY (or $env:STRATTA_API_KEY on Windows PowerShell).
If you copied from the UI, make sure no leading/trailing whitespace was added.

`ECONNREFUSED` / network errors

Confirm outbound HTTPS to *.convex.cloud is allowed by your firewall/VPN.
Try curl -I https://stratta.ch to verify general internet reachability.

Tools don't appear in Claude

Restart your Claude client after editing the config.
Check the MCP server logs (Claude Code: claude mcp logs stratta; Claude Desktop: ~/Library/Logs/Claude/mcp-server-stratta.log on macOS).
Make sure your Node.js version is >=20 (node --version).

Rate-limited

Each user can create up to 50 active keys and 20 new keys per 24h. Revoke unused keys in the dashboard.

`QUOTA_EXCEEDED`

Your organization reached one of its limits. The error names the dimension, your current count and the plan limit. Retrying will fail identically.

Limit	Free	Pro	Max
Norms	1	15	60
Sections	500	5,000	21,000
Figures	60	750	3,000
Queries / month	500	15,000	100,000
Members	1	1	5

Beyond Max, an Enterprise plan scales to 100 members, 300 norms and a million monthly queries; the calculator is at https://stratta.ch/tarifs

Stock limits free up when you delete a norm (ingest_delete). The monthly query counter resets on its own. Gauges live on the Workspace page of your dashboard, and an org admin can also set caps below the plan. Full details: https://stratta.ch/docs/en/account/plans

License

Proprietary — © Stratta, Lausanne. All rights reserved. This package is the official Stratta MCP client; redistribution, modification, or reuse of the source is not permitted without prior written consent.