docs: add MCP server documentation

docs/APIs-and-SDKs/MCP-Server/_category_.json

@@ -0,0 +1,6 @@
+{
+  "position": 4,
+  "collapsible": true,
+  "collapsed": true,
+  "label": "MCP Server"
+}

docs/APIs-and-SDKs/MCP-Server/authentication.mdx

@@ -0,0 +1,98 @@
+---
+title: Authentication
+sidebar_position: 4
+---
+
+# Authentication
+
+The ABsmartly MCP server supports two authentication methods. Both are
+configured per client — there are no server-side secrets, so credentials are
+always provided by your MCP client and isolated per connection.
+
+| Method | Best for | How it works |
+| --- | --- | --- |
+| **API Key** | Programmatic access, CI/CD, headless agents | Pass the key in HTTP headers or via the URL |
+| **OAuth** | Interactive use in Claude Desktop, Cursor, the web, etc. | Browser-based login via ABsmartly SAML |
+
+## API key
+
+API keys are issued from your ABsmartly instance under
+**Settings → API Keys**. They authenticate every request and identify which
+ABsmartly account the MCP session belongs to.
+
+### Where to pass the key
+
+Depending on the client, the API key is supplied as either:
+
+- An HTTP header (`Authorization: …` plus `x-absmartly-endpoint: …`), or
+- A query string parameter on the connection URL
+  (`?api_key=YOUR_API_KEY&absmartly-endpoint=https://your-instance.absmartly.com`).
+
+See the [Setup](./setup) guide for the exact configuration per client.
+
+### Authorization header formats
+
+When using API key authentication, these header formats are all supported:
+
+| Format | Example |
+| --- | --- |
+| Simple API key | `Authorization: BxYKd1U2...` |
+| Explicit `Api-Key` | `Authorization: Api-Key BxYKd1U2...` |
+| Subdomain shorthand | `Authorization: demo-1 BxYKd1U2...` |
+| Full domain | `Authorization: demo-1.absmartly.com BxYKd1U2...` |
+
+The **subdomain shorthand** auto-constructs the endpoint as
+`https://<subdomain>.absmartly.com/v1`, so you don't need to send a separate
+`x-absmartly-endpoint` header.
+
+## OAuth
+
+OAuth uses your existing ABsmartly login flow (SAML or username/password) and
+issues a JWT scoped to your MCP session. This is the recommended method for
+interactive clients like Claude Desktop, Cursor or the ChatGPT web app.
+
+When OAuth is configured, the MCP client opens a browser window the first time
+it connects. After you sign in, the client receives the token and the MCP
+connection is established. Subsequent connections reuse the cached token until
+it expires.
+
+### Specifying the instance URL
+
+OAuth needs to know which ABsmartly instance to log in against. You can
+provide this in either of two ways:
+
+- Add `?absmartly-endpoint=https://your-instance.absmartly.com` to the MCP
+  URL, or
+- Omit it — the OAuth flow will prompt you for the URL in the browser before
+  login.
+
+## Local stdio (CLI credentials)
+
+When running the server locally with `npx @absmartly/mcp`, authentication uses
+your ABsmartly CLI configuration and macOS Keychain credentials. Select a
+profile with `--profile=<name>` (for example, `--profile=production`).
+
+## Security model
+
+- **No server-side secrets** — credentials are always provided by the MCP
+  client.
+- **Session isolation** — each connection has its own credentials.
+- **OAuth protection** — API key sessions block OAuth discovery to prevent
+  authentication-method confusion.
+- **Destructive action confirmation** — `start`, `stop`, `archive` and
+  `delete` operations require explicit confirmation before they run (see the
+  [Tools Reference](./tools-reference#execute_command)).
+- **API error surfacing** — validation errors from the API are returned with
+  full detail so the assistant can correct them.
+
+## Checking who you are
+
+Once connected, you can confirm authentication and identity at any time with
+the `get_auth_status` tool:
+
+```text
+Are we authenticated?
+```
+
+The response includes the authenticated email, name, ABsmartly endpoint and the
+authentication type in use (`API Key` or `OAuth`).

docs/APIs-and-SDKs/MCP-Server/overview.mdx

@@ -0,0 +1,102 @@
+---
+title: Overview
+sidebar_position: 1
+---
+
+# ABsmartly MCP Server
+
+The ABsmartly [Model Context Protocol](https://modelcontextprotocol.io/) (MCP)
+server lets AI assistants — Claude, Cursor, VS Code, Windsurf, Gemini, ChatGPT
+and any other MCP-compatible client — operate the ABsmartly experimentation
+platform directly. The AI plans experiments, creates them, starts them, reads
+results and updates metrics, all through natural-language prompts.
+
+It exposes **230+ commands across 33 groups**: experiments, metrics, goals,
+teams, applications, segments, webhooks and more.
+
+## Why use it
+
+An MCP server turns ABsmartly into a "tool" your AI assistant can call. Instead
+of switching between your assistant, the ABsmartly UI and the API docs, you
+work in one place and the assistant does the rest.
+
+Typical workflows that get faster with MCP:
+
+- **Drafting experiments** from a description, including templates with goals,
+  metrics, variants and ownership prefilled
+- **Bulk operations** — "clone this experiment for the EU app, switch the unit
+  type to `device_id`, and update the audience"
+- **Reading state** — "what experiments are running this week and what's their
+  status?"
+- **Reviewing setups** — "find experiments without owners" or "list metrics
+  pending review"
+- **Cross-tool agentic work** — combine ABsmartly actions with code edits in
+  Cursor / Claude Code, or with Slack / Jira / Notion via other MCP servers
+
+## When to use MCP vs the alternatives
+
+| Use case | Best tool |
+| --- | --- |
+| Conversational, ad-hoc operations | **MCP server** |
+| Application code that assigns variants and tracks goals | [Client SDKs](/docs/APIs-and-SDKs/SDK-Documentation/getting-started) |
+| Programmatic automation, CI/CD, custom integrations | [Web Console API](/docs/APIs-and-SDKs/Web-Console-API/backend) |
+| Visual editing of pages for an A/B test | [LaunchPad browser extension](/docs/web-console-docs/launchpad-browser-extension/getting-started) |
+| Manual UI work | The ABsmartly Web Console |
+
+MCP isn't a replacement for the SDKs — application code still assigns variants
+and tracks goals via the SDK. MCP is for the **control plane**: configuring,
+launching and reviewing experiments and metrics.
+
+## How it works
+
+The server exposes just **4 tools** that give AI assistants access to the full
+ABsmartly CLI surface:
+
+| Tool | Purpose |
+| --- | --- |
+| `discover_commands` | Browse command groups or search by keyword |
+| `get_command_docs` | Get detailed docs for a specific command |
+| `execute_command` | Execute any command with typed parameters |
+| `get_auth_status` | Check authentication status |
+
+A typical interaction looks like this:
+
+```text
+"What experiments are running?"
+  → discover_commands(group: "experiments")
+  → execute_command(group: "experiments", command: "listExperiments",
+                    params: { state: "running" })
+```
+
+Destructive operations (`start`, `stop`, `archive`, `delete`) always require an
+explicit confirmation step before they run. Experiment creation from templates
+returns a preview first.
+
+See the [Tools Reference](./tools-reference) for the full surface.
+
+## Authentication at a glance
+
+| Method | Best for | How it works |
+| --- | --- | --- |
+| **OAuth** | Interactive use in Claude Desktop, Cursor, the web | Browser-based login via your ABsmartly SAML/SSO flow |
+| **API Key** | Programmatic access, CI/CD, headless | Pass the key in HTTP headers or via the URL |
+
+Both methods are documented in detail in [Authentication](./authentication).
+
+## What's next
+
+- **[Quick Start](./quick-start)** — connect Claude Desktop with OAuth and run
+  your first command in under five minutes
+- **[Setup](./setup)** — per-client setup for every supported MCP client
+- **[Authentication](./authentication)** — API key formats, OAuth flow,
+  security model
+- **[Usage Examples](./usage-examples)** — natural-language prompts that work
+  today
+- **[Tools Reference](./tools-reference)** — full list of tools, command groups,
+  resources and prompts
+- **[Troubleshooting](./troubleshooting)** — common errors and how to fix them
+
+## Source code
+
+The MCP server is open source under the MIT license:
+[github.com/absmartly/mcp](https://github.com/absmartly/mcp).

docs/APIs-and-SDKs/MCP-Server/quick-start.mdx

@@ -0,0 +1,112 @@
+---
+title: Quick Start
+sidebar_position: 2
+---
+
+# Quick Start
+
+This guide gets you from zero to running your first ABsmartly command via the
+MCP server in under five minutes. We'll use **Claude Desktop** with **OAuth**
+— the fastest path with no API keys to manage.
+
+For other clients or API key setups, jump straight to [Setup](./setup).
+
+## Prerequisites
+
+- **Claude Desktop** installed
+  ([download](https://claude.ai/download))
+- An ABsmartly account on your instance (the URL you log into, e.g.
+  `https://your-company.absmartly.com`)
+
+## 1. Add the connector
+
+In Claude Desktop, open **Settings → Connectors**, scroll to the bottom, and
+click **Add custom connector**.
+
+![Claude Desktop Connectors settings](./images/claude-desktop-connectors.png)
+
+In the dialog:
+
+- **Name:** `ABsmartly`
+- **Remote MCP server URL:**
+
+```text
+https://mcp.absmartly.com/sse?absmartly-endpoint=https://your-instance.absmartly.com
+```
+
+Replace `your-instance` with your ABsmartly subdomain.
+
+![Add custom connector dialog](./images/claude-desktop-add-custom-connector.png)
+
+Click **Add**, then **Connect**.
+
+## 2. Sign in
+
+Claude Desktop opens your browser. Sign in with your normal ABsmartly
+credentials (SAML/SSO if your org uses it). When the browser confirms success,
+the connector is live.
+
+:::tip
+If you didn't include `absmartly-endpoint` in the URL, the OAuth flow prompts
+you for it in the browser before login.
+
+![Connect to ABsmartly endpoint prompt](./images/oauth-endpoint-prompt.png)
+:::
+
+## 3. Verify the connection
+
+Back in Claude Desktop, start a new chat and try:
+
+```text
+Are we authenticated with ABsmartly?
+```
+
+The assistant calls `get_auth_status` and returns your email, name, instance
+endpoint and auth type (`OAuth`).
+
+## 4. Run your first command
+
+```text
+Show me the experiments that are currently running on ABsmartly
+```
+
+Behind the scenes the assistant calls:
+
+```text
+execute_command(group: "experiments", command: "listExperiments",
+                params: { state: "running" })
+```
+
+It returns the list, formatted for chat.
+
+## 5. Try something useful
+
+A few prompts that work out of the box (and don't change any state):
+
+```text
+List all metrics that are pending review
+```
+
+```text
+Which teams own experiments that have been running for more than 14 days?
+```
+
+```text
+Show me the goals defined for the "checkout" application
+```
+
+When you're ready to **create or change** something, the assistant will pause
+and show a preview / confirmation step — destructive actions like `start`,
+`stop`, `archive`, and `delete` always require explicit confirmation before
+they run.
+
+## Where to go next
+
+- **[Usage Examples](./usage-examples)** — more natural-language prompts that
+  work today
+- **[Tools Reference](./tools-reference)** — the full set of commands, including
+  experiment creation from markdown templates
+- **[Authentication](./authentication)** — switch to API key auth (for CI or
+  headless use), or learn about the security model
+- **[Troubleshooting](./troubleshooting)** — if the connection isn't working,
+  start here