# Authentication

> How to obtain a Alpha Ladder API key and understand the two authentication paths — OAuth 2.0 (hosted MCP) and direct token (local/npm MCP).

Alpha Ladder exposes a single public integration surface: an MCP server. There are two ways to authenticate against it, depending on which AI client you use.

## API keys

A Alpha Ladder API key is a secret credential that identifies a single user account. It begins with `sk-` and looks like:

```
sk-a1b2c3d4e5f6...
```

**Where to get one:** Log in to the [Alpha Ladder dashboard](https://www.alphaladder.hk/dashboard), find the **API Keys** section, and click **Generate New Key**. Copy it immediately — it is shown only once.

<Callout type="warn">Your API key grants full access to your Alpha Ladder account. Never commit it to source control, paste it into shared documents, or include it in logs. Treat it like a password.</Callout>

One API key maps to exactly one user account. If you need to revoke access, delete the key from the **API Keys** section in the dashboard; a replacement key can be generated at any time with no downtime.

## Hosted MCP (OAuth 2.0 + PKCE)

The hosted server at `https://www.alphaladder.hk/mcp` is protected by **OAuth 2.0 with PKCE** and dynamic client registration. This is the standard flow used by Claude.ai and other clients that connect via URL.

**From an end-user perspective, the flow is simple:** you enter the MCP URL into your client, click connect, and you are redirected to a Alpha Ladder consent page where you paste your `sk-…` API key and click **Allow**. That's it — you never see a client ID, code verifier, or token.

**What actually happens behind the scenes (for reference):**

1. Your client sends `POST /mcp` without credentials.
2. The server responds `401 Unauthorized` with a `WWW-Authenticate` header pointing to the discovery endpoints.
3. Your client fetches `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server` to discover the authorization server configuration.
4. Your client registers itself via `POST /oauth/register` (dynamic client registration — no pre-registration required).
5. Your client redirects you to `GET /oauth/authorize`, where the consent UI asks for your Alpha Ladder API key.
6. You paste your `sk-…` key and approve. The server issues an authorization code.
7. Your client exchanges the code for tokens via `POST /oauth/token`.
8. The server returns an **access token** (JWT, valid 1 hour) and a **refresh token** (valid 30 days). Your client stores and refreshes these automatically.

You do not need to manage tokens or handle the OAuth flow manually. Compliant MCP clients (Claude.ai, Cursor, Windsurf, Cline) implement this flow automatically.

## Local / npm MCP (`--token`)

When running Alpha Ladder's MCP package locally via npm, authentication bypasses OAuth entirely. You pass your API key directly as a command-line flag:

```bash
npx -y --package @metacomp/agentx-mcp agentx-mcp --token YOUR_API_KEY
```

The package sends the key as a `Bearer` token in the `Authorization` header on every request. There is no token expiry or refresh — the key is valid until revoked.

Claude Desktop uses this path, configured via `claude_desktop_config.json`. Claude Code also uses the direct-token path (passed via `--header`), not OAuth. VS Code can also connect this way by setting the `Authorization` header in `mcp.json`.

## Which client uses which

| Client | Auth path | How you provide the key |
|---|---|---|
| Claude.ai | OAuth 2.0 + PKCE (hosted MCP) | Paste `sk-…` once at the OAuth consent page |
| Claude Code | Direct Bearer token (header) | `--header "Authorization: Bearer YOUR_API_KEY"` on `claude mcp add` |
| Claude Desktop | Direct token (`--token` flag) | `"--token", "YOUR_API_KEY"` in `claude_desktop_config.json` |
| VS Code | Direct Bearer token (`mcp.json` headers) | `"Authorization": "Bearer ${input:metacomp-api-key}"` in `mcp.json` |
| Cursor / Windsurf / Cline | OAuth 2.0 + PKCE (hosted MCP) | Paste `sk-…` once at the OAuth consent page |

---

There is no public REST API. All access to Alpha Ladder's capabilities — for both end-users and automated agents — goes through MCP. For a conceptual overview of how MCP works and what products are available, see [Core Concepts](/developers/getting-started/core-concepts).