Connecting to Alphractal MCP

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)
OAuth (browser-based 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.

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
Cursor / VS Code
MCP Inspector
Any OAuth client

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.

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"
      }
    }
  }
}

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

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”.

​The endpoint

​Authenticating

​Client configuration

​Checking that it works

​When it refuses

The endpoint

Authenticating

Client configuration

Checking that it works

When it refuses