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

# The Graph MCP

> Connect AI agents directly to the Nile Markets subgraph via The Graph's hosted MCP server at subgraphs.mcp.thegraph.com — raw GraphQL access to all 14 indexed entities.

The Graph hosts an MCP server that exposes any deployed subgraph — including Nile Markets — as a tool for AI agents. Instead of typed tools, you get raw GraphQL access to all 14 indexed entities with full filtering, pagination, and aggregation.

## Prerequisites

You need a Graph API key for all usage (including testnet). Create one at [thegraph.com/studio](https://thegraph.com/studio).

## Setup

The Graph MCP uses SSE transport, which requires `mcp-remote` as a local proxy. The server name (`nile-graph` below) is a local alias you choose — it's how your agent identifies this MCP connection.

<Tabs>
  <Tab title="Claude Desktop">
    Add to your `claude_desktop_config.json` (Settings > Developer > Edit Config):

    ```json theme={null}
    {
      "mcpServers": {
        "nile-graph": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "--header",
            "Authorization:${AUTH_HEADER}",
            "https://subgraphs.mcp.thegraph.com/sse"
          ],
          "env": {
            "AUTH_HEADER": "Bearer YOUR_GRAPH_API_KEY"
          }
        }
      }
    }
    ```

    Replace `YOUR_GRAPH_API_KEY` with your key from [Subgraph Studio](https://thegraph.com/studio), then restart Claude Desktop.
  </Tab>

  <Tab title="Cursor">
    Add to `.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "nile-graph": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "--header",
            "Authorization:${AUTH_HEADER}",
            "https://subgraphs.mcp.thegraph.com/sse"
          ],
          "env": {
            "AUTH_HEADER": "Bearer YOUR_GRAPH_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

After connecting, add `graphql://subgraph` as a resource in your agent's context to activate the MCP tools. You specify which subgraph to query at query time — by deployment ID, subgraph ID, or keyword search.

<Warning>
  The Graph MCP does not support direct HTTP transport. You must use the `npx mcp-remote` proxy as shown above. Claude Code's `claude mcp add --transport http` will not work for this server.
</Warning>

## Available Entities

The Nile Markets subgraph indexes 13 entity types across protocol state, positions, oracle data, and analytics.

| Entity                | Type      | Description                                                                                          |
| --------------------- | --------- | ---------------------------------------------------------------------------------------------------- |
| **Position**          | Mutable   | Open and closed FX forward positions with PnL, margin, and lifecycle state                           |
| **Account**           | Mutable   | Trader margin accounts with collateral, locked amounts, and position counts                          |
| **PoolState**         | Mutable   | Liquidity pool metrics — TVL, utilization, share price, exposure                                     |
| **ProtocolState**     | Mutable   | Operating mode (NORMAL, DEGRADED, REDUCE\_ONLY, PAUSED)                                              |
| **DailyStats**        | Mutable   | Daily volume, fees, position opens/closes, and pool PnL                                              |
| **OracleRound**       | Immutable | Published forward price rounds — dedupe by `fixingTimestamp` sorted by `publishTime` desc for latest |
| **TxFeeAccumulator**  | Mutable   | Running fee totals by category                                                                       |
| **PoolTransaction**   | Immutable | Vault deposit and withdrawal events                                                                  |
| **FeeEvent**          | Immutable | Individual fee charges (trading, liquidation, termination, oracle)                                   |
| **FixingPrice**       | Immutable | Recorded spot prices at maturity for settlement                                                      |
| **VaultEvent**        | Immutable | ERC-4626 vault share mint/burn events                                                                |
| **ModeTransition**    | Immutable | Protocol mode change history                                                                         |
| **PositionReduction** | Immutable | Partial position reduction events                                                                    |

**Mutable** entities reflect current state and are updated over time. **Immutable** entities are append-only event records that never change after creation.

## Example Queries

Once connected, your agent can run arbitrary GraphQL against the Nile Markets subgraph.

**Fetch all open positions for an account:**

```graphql theme={null}
{
  positions(
    where: { account: "0xabc...", status: "OPEN" }
    orderBy: openedAt
    orderDirection: desc
    first: 25
  ) {
    id
    side
    tenor
    notional
    entryStrike
    margin
    openedAt
  }
}
```

**Get current pool metrics:**

```graphql theme={null}
{
  poolState(id: "pool") {
    totalAssets
    totalShares
    sharePrice
    utilization
    longExposure
    shortExposure
  }
}
```

**Query daily stats for the past week:**

```graphql theme={null}
{
  dailyStats(
    orderBy: date
    orderDirection: desc
    first: 7
  ) {
    date
    volume
    fees
    positionsOpened
    positionsClosed
  }
}
```

## Graph MCP vs Nile MCP

Both give AI agents access to Nile Markets data. They serve different use cases.

| Capability           | Graph MCP                                       | Nile MCP                                   |
| -------------------- | ----------------------------------------------- | ------------------------------------------ |
| **Access method**    | Raw GraphQL queries                             | 22 typed tools                             |
| **Data source**      | Subgraph only                                   | Subgraph + RPC                             |
| **Write operations** | No                                              | 8 tools (unsigned calldata)                |
| **Real-time prices** | No (subgraph lag)                               | Yes (RPC reads)                            |
| **Response format**  | Raw GraphQL JSON                                | Structured envelope with protocol metadata |
| **Custom queries**   | Full GraphQL flexibility                        | Fixed tool schemas                         |
| **Setup**            | Graph API key required + `npx mcp-remote` proxy | No auth required (M2 testnet)              |
| **Entity access**    | All 14 entities, any field combination          | Curated subsets per tool                   |

**Use Graph MCP when** you need custom queries, cross-entity joins, or aggregations that the typed tools don't support — for example, filtering positions by multiple criteria simultaneously or computing custom analytics across entities.

**Use Nile MCP when** you want structured interactions with response formatting, real-time RPC data (current prices, live PnL), or write operation calldata. The Nile MCP server is at `mcp.nilemarkets.com/api/mcp` — see [MCP Server](mcp-server) for setup.

<Tip>
  You can use both servers simultaneously. Use Nile MCP for standard operations and fall back to Graph MCP for custom analytics queries.
</Tip>