> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alphractal.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Tabs>
  <Tab title="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](https://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.
  </Tab>

  <Tab title="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.
  </Tab>
</Tabs>

## Client configuration

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    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.
  </Tab>

  <Tab title="Cursor / VS Code">
    Add the server to your MCP configuration file:

    ```json theme={null}
    {
      "mcpServers": {
        "alphractal": {
          "type": "http",
          "url": "https://mcp.alphractal.com/mcp",
          "headers": {
            "X-Alphractal-Key": "YOUR_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="MCP Inspector">
    Useful for checking a key or browsing the catalog before wiring a client:

    ```bash theme={null}
    npx -y @modelcontextprotocol/inspector --cli https://mcp.alphractal.com/mcp \
      --transport http \
      --header "X-Alphractal-Key: YOUR_API_KEY" \
      --method tools/list
    ```
  </Tab>

  <Tab title="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.
  </Tab>
</Tabs>

## 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                          |

<Note>
  A refusal is not an empty result. `access_denied` and `no_data` mean different things, and
  neither is "the answer is zero".
</Note>