#Claude Code

The MCP server is registered under the name **x3**, so its tools appear as mcp__x3__* and its prompts as /mcp__x3__install. Setups registered under the old name 3x keep working – the onboarding prompts look for the tool setup_status on either server. The easiest way to connect is the dashboard: Onboarding → Tracking einbauen → Mit Claude Code einrichten or Claude verbinden (Guided onboarding).

#Scope: this folder or every folder

claude mcp add stores the server in your personal Claude Code configuration:

• --scope local – only when Claude Code runs in the current folder. Use it inside the website repository you are installing X3 in.
• --scope user – in every folder. Good for analysis ("How did my website do last week?").
• Never --scope project: it writes .mcp.json into the repository – with a key in the header that would end up in git.

#Keyless setup (OAuth)

claude mcp add --transport http --scope local x3 https://api.x3.example/mcp

Then type /mcp in Claude Code → choose x3 → Authenticate. Claude can read the docs and setup recipes right away; tools that need your data run the OAuth 2.1 flow (dynamic client registration + PKCE) in the browser:

1. Sign in to X3 (or follow Create an account when sign-up is enabled on the deployment).
2. Consent: choose the organizations and – recommended – only the project Claude should work on; choose Read only for analysis. Installing X3 needs Read and write, which can also change conversions and ad settings – choose it only when you let Claude install. Administer organizations (keys, members) and Personal data (leads) are opt-in boxes.
3. The browser hands the authorization code back to Claude Code on a loopback address (http://127.0.0.1:<port>/callback); Claude Code stores the tokens. Access tokens live one hour and are refreshed automatically for up to 180 days of inactivity.

Your effective permissions are always the intersection of the consent and your current role in each organization – demoting you in the dashboard takes effect on the next call. Revoke the grant in the dashboard's account settings (Connected apps; admins see all grants of the organization).

#Secret key from the onboarding

Organization admins can create a key for Claude Code in the onboarding ("Schlüssel für Claude Code erzeugen"). It is narrowed to the project, expires after 90 days and is shown once. Run the command in your terminal, never paste the key into a chat. Recommended – the key is typed at a hidden prompt and stays out of the shell history:

read -rs X3_KEY && claude mcp add --transport http --scope local x3 https://api.x3.example/mcp --header "Authorization: Bearer $X3_KEY"; unset X3_KEY
claude mcp get x3

claude mcp get x3 shows connected once it works. The one-line variant with the key embedded (--header "Authorization: Bearer sk_3x_…") lands in your shell history – prefer the one above (PowerShell: run Clear-History afterwards). The key is stored in plain text in your personal Claude Code configuration (~/.claude.json), which is why it is least-privilege:

When a tool answers insufficient_scope, Claude tells you which step to do in the dashboard.

#Proxy key ownership

The proxy key (X3_PROXY_KEY) is always created by you in the dashboard ("Proxy-Schlüssel erzeugen"), never by Claude: a key minted through a Claude key or an OAuth sign-in is derived from it and stops working when that expires or is revoked. The onboarding prompts call setup_generate_snippet with mint_proxy_key: false; see Proxy key ownership.

#Install X3 on a website

Paste the prompt "SDK einbauen" from the dashboard into Claude Code inside your site's repository (or run /mcp__x3__install). Claude follows this workflow:

1. setup_status – reads the project, publishable key and what is still open.
2. setup_detect_stack – framework, router, TypeScript, CSP; the hosting decides the proxy option.
3. setup_generate_snippet – one call with framework, proxy option, consent integration and mint_proxy_key: false; Claude applies the files and keeps the publishable key public and every secret out of the code.
4. Cookie banner, page changes (SPA) and CSP – with your OK for anything legal or security-related.
5. Build and grep -rEl "sk_3x_[0-9A-Za-z]{46}" .next/static dist build out over the browser output – no key may reach the browser (the bare prefix sk_3x_ in .next/server is the SDK's key check, not a leak).
6. Function test: setup_verify_installation with the public URL, a test visit (?x3_test=1) watched with events_tail and include_test: true, page changes, consent, proxy, and a final setup_status.

Follow-up prompts: "Ereignisse & Ziele", "Serverseitige Conversions", "Analyse mit Claude", "Fehlersuche" and "Verbindung testen" (also as /mcp__x3__events, /mcp__x3__server_conversions, /mcp__x3__analysis, /mcp__x3__debug_tracking, /mcp__x3__connection_test).

#Keys for CI and agents

For CI, headless machines or agents without a browser, create a secret key under Organization → API keys with the scopes the agent needs (Scopes and roles) and pass it as a header. Keep the key in the environment; a committed .mcp.json may only reference it:

{
  "mcpServers": {
    "x3": {
      "type": "http",
      "url": "https://api.x3.example/mcp",
      "headers": { "Authorization": "Bearer ${X3_SECRET_KEY}" }
    }
  }
}

With a secret key, a tool outside the key's scopes is not listed and calling it returns a tool error naming the missing scope.

#Troubleshooting

The onboarding's step "Claude verbinden" shows the last MCP calls for the project – including a failed call that never reached a project (e.g. a scope error) – so you can see whether Claude Code is connected.