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

# MCP Server

> Configure the @0xarchive/mcp-server package for MCP-capable clients with typed 0xArchive market-data tools.

MCP is the interface for AI clients, coding agents, editors, and local runtimes that should call 0xArchive through typed tools, resources, and prompts instead of free-form endpoint guesses.

The public package is `@0xarchive/mcp-server`. It runs as a local stdio server with Node 18 or newer, uses `OXARCHIVE_API_KEY`, and exposes typed tools across Hyperliquid core, Hyperliquid Spot, HIP-3, HIP-4, Lighter, WebSocket-adjacent workflows, and data quality.

Mintlify also exposes a separate Docs MCP surface for documentation search and virtual-docs access. Its discovery JSON lives at `https://docs.0xarchive.io/.well-known/mcp`; its streamable HTTP MCP transport lives at `https://docs.0xarchive.io/mcp` and responds to JSON-RPC MCP requests. Use this page for the Market Data MCP Server package, and do not link `/mcp` as human setup documentation.

<Note>
  MCP is a protocol/tool surface, not a coding agent. Claude Code, Codex, Cursor, Windsurf, and similar clients may consume MCP servers when their setup supports MCP.
</Note>

## Install And Run

<Steps>
  <Step title="Set the API key">
    Store the key in the environment used by the MCP client.

    ```bash theme={"theme":"github-dark"}
    export OXARCHIVE_API_KEY="0xa_your_api_key"
    ```
  </Step>

  <Step title="Run the server">
    Use the published package as the default path.

    ```bash theme={"theme":"github-dark"}
    npx -y @0xarchive/mcp-server
    ```
  </Step>

  <Step title="Ask the client for a bounded call">
    Start with one venue, one symbol, and one small window before widening the workflow.
  </Step>
</Steps>

## First Tool Contract

After configuration, ask for one narrow market-data call and expect either a concrete 0xArchive tool result or a direct auth/configuration error from the client.

| Prompt shape                                              | Expected tool family                                    |
| --------------------------------------------------------- | ------------------------------------------------------- |
| "Get a BTC market summary on Hyperliquid."                | `get_summary`                                           |
| "Fetch ETH one-hour candles for the last 24 hours."       | `get_candles`                                           |
| "Compare current BTC funding on Hyperliquid and Lighter." | `get_funding_current` and `get_lighter_funding_current` |
| "Show recent data incidents or coverage gaps."            | Data quality and incident tools                         |
| "Summarize `km:US500` on HIP-3."                          | HIP-3 summary tools                                     |
| "List active HIP-4 outcome markets."                      | HIP-4 outcome tools                                     |

If the client cannot name or call a 0xArchive tool, fix MCP configuration before asking for broader analysis.

## Client Recipes

<CodeGroup>
  ```bash Claude Code theme={"theme":"github-dark"}
  claude mcp add 0xarchive \
    -s user \
    -t stdio \
    -e OXARCHIVE_API_KEY="$OXARCHIVE_API_KEY" \
    -- npx -y @0xarchive/mcp-server
  ```

  ```json Generic MCP client theme={"theme":"github-dark"}
  {
    "mcpServers": {
      "0xarchive": {
        "command": "npx",
        "args": ["-y", "@0xarchive/mcp-server"],
        "env": {
          "OXARCHIVE_API_KEY": "${OXARCHIVE_API_KEY}"
        }
      }
    }
  }
  ```

  ```text Codex / Cursor / Windsurf theme={"theme":"github-dark"}
  Add the same stdio server command in the host's MCP settings:

  command: npx
  args: -y @0xarchive/mcp-server
  env: OXARCHIVE_API_KEY=<stored in the host secret or environment store>
  ```
</CodeGroup>

## When To Use MCP Server

| Use MCP Server when                                                        | Use another interface when                                                 |
| -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| The client can call MCP tools directly                                     | You only need one shell command; use [CLI](/cli)                           |
| You want typed tool calls instead of prompt-only docs                      | You are generating an app client; use [OpenAPI](/openapi) or [SDKs](/sdks) |
| The same local configuration should be shared across agent sessions        | The host only supports `SKILL.md`; use [Skill](/skill)                     |
| You want route selection, execution, and response inspection in one client | You need raw HTTP behavior; use [REST API](/rest-api)                      |

## Tool Boundaries

Market-data tools are read-only and idempotent: summaries, order books, trades, candles, funding, open interest, liquidations, instrument discovery, freshness, coverage, latency, incidents, and SLA checks. Web3 auth, account, key, subscription, or payment-related tools can create or change account state; require explicit human approval before an agent calls them.

The MCP Server exposes typed tools for REST-shaped and historical workflows. For live streaming, use [WebSocket](/websocket) or a CLI stream command instead of assuming the MCP client maintains a realtime feed.

## Prompt Defaults To Name

Name these fields in the user or system prompt when you want deterministic agent behavior.

| Field            | Example                                                                                           |
| ---------------- | ------------------------------------------------------------------------------------------------- |
| Venue family     | Hyperliquid core, Hyperliquid Spot, HIP-3, HIP-4, or Lighter                                      |
| Symbol or market | `BTC`, `ETH`, `km:US500`, HIP-4 outcome ID, or `HYPE-USDC`                                        |
| Time window      | last 24 hours, explicit ISO start/end, interval, limit, and cursor if paginating                  |
| Output goal      | market summary, candles, funding comparison, freshness check, incident check, or route validation |
| Quality bar      | include freshness, coverage, request ID, or pagination state in the answer                        |

If a required field is missing, ask the client to clarify before widening the market, venue, or historical window.

## Security Notes

Keep API keys out of prompts and checked-in config. Prefer environment variables, host secret stores, or project-local ignored files. Review local MCP server configuration before enabling broad tool permissions in an agent host.

## Local Stdio Model

The documented setup is local stdio: the agent host launches `npx -y @0xarchive/mcp-server`, passes `OXARCHIVE_API_KEY` through environment configuration, and communicates with the server through the MCP client. Do not configure a remote hosted MCP URL unless 0xArchive has published one for your environment.

## Operational Fit

Use MCP when the host can call tools directly and you want structured market-data operations without asking the model to paste curl commands. Use CLI when terminal output is enough. Use Skill when the host supports reusable `SKILL.md` procedures. Use OpenAPI when the job is generated clients or route review.

## Why 0xArchive Fits

0xArchive’s MCP Server gives MCP-capable clients direct access to the same route families described in the REST reference: Hyperliquid core, Hyperliquid Spot, HIP-3, HIP-4, Lighter, and data quality. That makes it practical for agents to inspect freshness, choose a venue family, and fetch a bounded market-data window without inventing endpoints.

## Next Step

Use [Choose An Interface](/tooling) if you are deciding between MCP Server, CLI, Skill, SDKs, and OpenAPI. Use [Coding Agents](/coding-agents) for prompt and recovery rules after the server is configured.