Quickstart — TwinEthos

Hosted access is opening to design partners. The hosted endpoint below is issued with your API key; until your key is live, TwinEthos runs locally (see Running locally).

1. Get an API key

Request access. Each design partner receives a key for the hosted endpoint:

https://api.twinethos.com/mcp

The server speaks MCP over streamable HTTP. Send the key in either header:

Authorization: Bearer YOUR_API_KEY
X-API-Key: YOUR_API_KEY

Requests without a valid key get 401. Keep the key out of source control: the examples below read it from an environment variable or prompt for it. We store only a hash of each key; to rotate one, ask us for a new key.

2. Connect your coding agent

Claude Code

From your project directory:

claude mcp add --transport http twinethos https://api.twinethos.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Add --scope user to use it in every project, or --scope project to write a shared .mcp.json. To share the config without the key, commit this .mcp.json and set TWINETHOS_API_KEY in each developer's environment:

.mcp.json

{
  "mcpServers": {
    "twinethos": {
      "type": "http",
      "url": "https://api.twinethos.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TWINETHOS_API_KEY}"
      }
    }
  }
}

Reference: Claude Code — Connect to tools via MCP.

Cursor

Project config in .cursor/mcp.json, or global config in ~/.cursor/mcp.json:

.cursor/mcp.json

{
  "mcpServers": {
    "twinethos": {
      "url": "https://api.twinethos.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:TWINETHOS_API_KEY}"
      }
    }
  }
}

Reference: Cursor — Model Context Protocol.

VS Code with GitHub Copilot (agent mode)

Workspace config in .vscode/mcp.json. VS Code prompts for the key once and stores it securely:

.vscode/mcp.json

{
  "servers": {
    "twinethos": {
      "type": "http",
      "url": "https://api.twinethos.com/mcp",
      "headers": {
        "X-API-Key": "${input:twinethos-api-key}"
      }
    }
  },
  "inputs": [
    {
      "id": "twinethos-api-key",
      "type": "promptString",
      "description": "TwinEthos API key",
      "password": true
    }
  ]
}

References: VS Code — Add and manage MCP servers; MCP configuration reference.

Other MCP clients

Any client that supports remote (streamable HTTP) MCP servers with custom headers can connect. The usual shape is below; check your client's documentation for the exact key names.

{
  "twinethos": {
    "url": "https://api.twinethos.com/mcp",
    "headers": {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  }
}

To check your key outside an editor:

curl -sS https://api.twinethos.com/mcp \
  -H "Authorization: Bearer $TWINETHOS_API_KEY" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

3. The MCP tools

All tools are read-only. Every response carries the not-legal-advice notice, the date of the data, and each rule's review status.

Tool	Arguments	Returns
`review_checklist`	`patterns, jurisdictions, include_guardrails, guardrail_classes, limit, offset, compact`	The detectors to apply, most-exposed first (binding law, then standards, then recommended guardrails): the citation, who each duty applies to, whether code can show it, and the concrete sources, sinks, settings, and patterns to look for. Paged: call again with next_offset until it is absent. compact: true gives one short record per rule, best for smaller models. Start every review here.
`get_rule`	`rule_id, include_source_text`	One rule in full: citation, official URL, retrieval date, verbatim text for government-edict sources (never licensed standards text), detectors, lifecycle, and for recommended guardrails the incident evidence.
`find_rules`	`jurisdictions, patterns, condition, tier, text, include_guardrails, limit`	Rule summaries matching a jurisdiction (ISO codes such as EU or US-CA; US matches every state), integration pattern, control condition, enforceability tier, or free text. Binding law first.
`get_condition`	`condition_id`	A control condition or family with computed convergence: which authorities address it, where binding law is in force, and which recommended guardrails build on it.
`list_guardrails`	`priority_set, guardrail_class`	TwinEthos recommended guardrails (opinion, not law), filtered by set or class.
`changes_since`	`date, conditions`	What changed on or after a date: rule changes between data releases (optionally only those touching given controls), plus rules authored and official sources re-captured since then.

4. Run a review

Ask your agent in plain language, naming what the app does and where its users are:

Use TwinEthos to review this repo. It is an agentic support bot with users in the EU and California.

The agent calls review_checklist with:

patterns — the repository's AI integration patterns: chat, rag, agentic, decision_pipeline, content_generation, classification, recommendation, embeddings.
jurisdictions — where users are, as codes such as EU, US-CA, US-CO; US matches every state.
guardrail_classes (optional) — law_derived, agent_security, and operational_integrity are included by default; add ethical_use to opt in to the advisory ethical-use guardrails.

It then inspects the files each detector names and reports each finding as detected, not_detected, or insufficient_evidence, with file and line evidence and the rule id. For any finding, get_rule returns the citation, the official URL, and the verbatim government text to check it against.

5. Read the four lanes

Lane	Meaning
Binding law — in force	Law that applies now: a current legal-exposure question for your counsel.
Binding law — not yet in force or stayed	Enacted but not yet applicable (or stayed): reported with its applies-from date, never as a current violation.
Standard / soft law	NIST, ISO, IEEE, OECD, sector guidance: a gap against a named standard.
TwinEthos recommendation (not law)	TwinEthos's own recommendation: what a responsible AI integration does anyway. Opinion, never law.

Binding law — in force: take these to whoever owns legal exposure first, with the cited text.
Not yet in force: plan the fix before the applies-from date; it is not a current violation.
Standard / soft law: a gap against the named standard or framework; matters when you claim to follow it.
TwinEthos recommendation: our opinion of good practice, never law. Prioritize by your own risk.

Two more signals travel with each item. evidence_scope: organizational means code cannot show the duty (a document or process is the evidence). requires_human_determination means applicability depends on facts outside the repository — who you are, where your users are, what the system decides.

6. Running locally

Design partners with a TwinEthos checkout or data release can run the same server over stdio:

pip install -e ".[mcp]"
claude mcp add twinethos -- twinethos-mcp --local-tools

Set TWINETHOS_DATA to point the server at a released data directory. --local-tools adds triage_repository, which runs TwinEthos's detectors over a repository on your machine and points the agent at the files and lines to check; nothing leaves the machine. The hosted server never offers it. The same triage runs from a shell: twinethos-mcp --triage PATH --patterns chat --jurisdictions US-CA.