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

# Connect to the AX MCP Server

> Set up the Arize AX MCP server in Claude Code, Cursor, or Codex with an API key, then verify the connection and troubleshoot auth errors.

The MCP server is hosted, so there is nothing to install. You need two things: the [endpoint for your region](/docs/api-clients/mcp/endpoints) and an [Arize API key](/docs/api-clients/mcp/authentication).

## Add the server to your client

<Tabs>
  <Tab title="Claude Code">
    <Steps>
      <Step title="Register the server">
        Registering at project scope writes to `.mcp.json` in the repository root:

        ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
        claude mcp add-json arize-ax --scope project '{
          "type": "http",
          "url": "https://api.arize.com/mcp",
          "headers": {"Authorization": "Bearer ${ARIZE_API_KEY}"}
        }'
        ```

        Use `--scope user` instead to make the server available in every project on your machine.
      </Step>

      <Step title="Check the connection">
        Run `claude mcp list`, which shows whether each server connected, or run `/mcp` inside Claude Code for interactive status.
      </Step>

      <Step title="Remove it (optional)">
        Run `claude mcp remove arize-ax`.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Cursor">
    <Steps>
      <Step title="Add the server">
        Go to `Settings` → `MCP` → **Add new global MCP server**, then add this entry to the JSON config:

        ```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
        "arize-ax": {
          "type": "http",
          "url": "https://api.arize.com/mcp",
          "headers": {"Authorization": "Bearer ${ARIZE_API_KEY}"}
        }
        ```
      </Step>

      <Step title="Restart Cursor">
        Restart Cursor if the tools do not appear.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Codex">
    <Steps>
      <Step title="Register the server">
        Registering with the CLI writes to `~/.codex/config.toml`:

        ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
        codex mcp add arize-ax --url https://api.arize.com/mcp --bearer-token-env-var ARIZE_API_KEY
        ```

        `--bearer-token-env-var` points Codex at the name of the environment variable holding your key, so the key itself never lands in `config.toml`. Codex sends it as `Authorization: Bearer <value>` on every request.
      </Step>

      <Step title="Check the connection">
        Run `codex mcp get arize-ax`, or list every configured server with `codex mcp list`. Remove it with `codex mcp remove arize-ax`.
      </Step>

      <Step title="Or edit config.toml directly">
        ```toml theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
        [mcp_servers.arize-ax]
        url = "https://api.arize.com/mcp"
        bearer_token_env_var = "ARIZE_API_KEY"
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Other clients">
    Any client that speaks Streamable HTTP and supports custom headers works. The config shape is the same:

    ```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    {
      "mcpServers": {
        "arize-ax": {
          "type": "http",
          "url": "https://api.arize.com/mcp",
          "headers": {"Authorization": "Bearer ${ARIZE_API_KEY}"}
        }
      }
    }
    ```

    Some clients expand `${...}` from your environment and some do not. If the connection fails with an auth error, replace the placeholder with the key directly to rule it out.

    A few clients take a top-level `"auth"` field instead of `headers` and send it as `Authorization: Bearer <key>` for you.
  </Tab>
</Tabs>

## Verify the connection

Ask your agent something that requires a tool call, such as "list my Arize projects." It should call `list_projects` and come back with names rather than a guess.

To test outside a client, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) CLI. It needs Node 22.19.0 or newer and runs through `npx` with no install:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
npx @modelcontextprotocol/inspector --cli https://api.arize.com/mcp \
  --transport http \
  --header "Authorization: Bearer $ARIZE_API_KEY" \
  --method tools/list \
  --format json | jq .result
```

Call a tool the same way:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
npx @modelcontextprotocol/inspector --cli https://api.arize.com/mcp \
  --transport http \
  --header "Authorization: Bearer $ARIZE_API_KEY" \
  --method tools/call \
  --tool-name list_projects \
  --tool-arg name=my-project \
  --format json | jq .result
```

The CLI exits non-zero on failure. Exit code `3` means authentication failed and exit code `4` means the server was unreachable.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The client connects but no tools appear">
    Confirm the transport is Streamable HTTP. A client configured for `stdio` will try to run the URL as a command, and one configured for `sse` will hang on a connection the server does not offer. Set `"type": "http"`, or pass `--transport http` on the Inspector CLI.
  </Accordion>

  <Accordion title="Authorization errors on every call">
    The header must be `Authorization: Bearer <your-arize-api-key>`. The bare key also works, but the word `Bearer` with nothing after it is rejected.

    If the value looks right, your client probably did not expand `${ARIZE_API_KEY}`. Paste the key directly to confirm, then move it back into an environment variable once the connection works.
  </Accordion>

  <Accordion title="A tool returns 404 for a resource I know exists">
    The REST API returns `404` when the caller has no read access, rather than `403`, so that nobody can enumerate resources by probing IDs. A `404` on something you can see in the UI usually means the key lacks read access to that space or project, or belongs to a different region. See [authorization](/docs/ax/rest-reference/overview#authorization).
  </Accordion>

  <Accordion title="Requests start failing with 429">
    Rate limits apply per API key, defaulting to 100 requests per minute on a rolling window. An agent paging through a large span set can reach that. Wait for the window to reset, and narrow your filters so fewer pages are needed. See [rate limits](/docs/ax/rest-reference/overview#rate-limits).
  </Accordion>

  <Accordion title="A browser-based client cannot connect">
    The server rejects requests that carry an `Origin` header, which means browser clients are blocked by default, including the Inspector web UI. Use the Inspector CLI shown above, or a client that runs as a native process.
  </Accordion>

  <Accordion title="A plain GET on the endpoint returns an error">
    Only the `/mcp` prefix is routed publicly, and a bare `GET` or `HEAD` against it returns a protocol error rather than a health signal. To check reachability, make a `tools/list` call.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Endpoints" icon="globe" href="/docs/api-clients/mcp/endpoints">
    Regional URLs for the MCP server.
  </Card>

  <Card title="Authentication" icon="key" href="/docs/api-clients/mcp/authentication">
    Get an API key and see how bearer token auth works.
  </Card>

  <Card title="Tool catalog" icon="list" href="/docs/api-clients/mcp/tool-catalog">
    Every tool your agent can now call, with arguments and pagination rules.
  </Card>

  <Card title="Skills" icon="sparkles" href="/docs/ax/skills/overview">
    Add the write side: datasets, experiments, evaluators, and prompt optimization.
  </Card>
</CardGroup>