Authentication

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, find the API Keys section, and click Generate New Key. Copy it immediately — it is shown only once.

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:

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

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.