Connecting to Alphractal MCP

The server endpoint, the two ways to authenticate, and configuration for the common MCP clients.

The endpoint

https://mcp.alphractal.com/mcp

Transport is streamable HTTP. The server is stateless — there is no session to keep alive and no SSE endpoint to hold open.

Authenticating

Two schemes work, and the server advertises both.

API key (headless clients)

Send your Alphractal API key in either header:

X-Alphractal-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

Create and revoke keys at app.alphractal.com/api-dashboard. It is the same key the REST API uses.

This is the path for Claude Code, IDE assistants, the MCP Inspector and your own scripts — anything that can set a header.

OAuth (browser-based clients)

The server implements OAuth 2.1 with protected-resource metadata. A client that supports it discovers everything on its own — you paste the server URL and sign in with your Alphractal account, with no key to copy.

WWW-Authenticate: Bearer resource_metadata="https://mcp.alphractal.com/.well-known/oauth-protected-resource/mcp"

Authorization server: https://auth.alphractal.com/, with dynamic client registration.

Client configuration

Claude Code

claude mcp add --transport http alphractal https://mcp.alphractal.com/mcp \
  --header "X-Alphractal-Key: YOUR_API_KEY"

Then /mcp inside Claude Code lists the server and its tools.

Cursor / VS Code

Add the server to your MCP configuration file:

{
  "mcpServers": {
    "alphractal": {
      "type": "http",
      "url": "https://mcp.alphractal.com/mcp",
      "headers": {
        "X-Alphractal-Key": "YOUR_API_KEY"
      }
    }
  }
}

MCP Inspector

Useful for checking a key or browsing the catalog before wiring a client:

npx -y @modelcontextprotocol/inspector --cli https://mcp.alphractal.com/mcp \
  --transport http \
  --header "X-Alphractal-Key: YOUR_API_KEY" \
  --method tools/list

Any OAuth client

Clients that speak OAuth need no configuration beyond the URL:

https://mcp.alphractal.com/mcp

The client discovers the authorization server, registers itself and sends you through a normal Alphractal sign-in.

Checking that it works

Ask the client to list the tools, or call get_my_plan — it answers with your plan and the limits attached to it, which confirms both the transport and the credentials in one call.

When it refuses

Every tool answers with the same envelope, so the failure tells you which of these it is:

What you see	What it means	What to do
401 with WWW-Authenticate	No credential reached the server	Check the header name and that the key is active
access_denied	The tool is above your plan	The message names the plan that lifts it; retrying will not help
quota_exceeded	Per-minute request budget, not a plan wall	Back off for the seconds reported, then retry
no_data	The metric exists but not for that asset or window	Widen the window or check coverage for the asset
invalid_arguments	The call is malformed	The message names the argument at fault

A refusal is not an empty result. access_denied and no_data mean different things, and neither is “the answer is zero”.